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About  the  X  Toolkit 

The  X  Toolkit  is  the  collective  name  for  two  C-language  subroutine  libraries  (Xt  and  Xaw) 
designed  to  simplify  the  development  of  X  Window  System  applications  using  reusable  com 
ponents  called  widgets.  Typical  widgets  include  scrollbars,  menus,  dialog  boxes,  text-editing 
areas,  drawing  areas,  etc.  Each  widget  is  made  up  of  its  own  X  window,  but  most  of  the  work 
that  goes  on  in  that  window  has  already  been  taken  care  of — all  the  application  programmer 
has  to  do  is  assemble  the  widgets  and  write  application-specific  code  that  will  be  called  in 
response  to  events  in  the  widgets. 

The  Xt  library  (the  Intrinsics)  consists  of  routines  for  using  and  building  widgets.  Widgets 
are  defined  using  an  object-oriented  classing  mechanism.  The  Xaw  widget  library  is  based 
on  Xt  and  provides  a  small  number  of  widgets  that  can  be  used  to  write  simple  application 
programs. 

The  Xt  Intrinsics  are  written  using  Xlib,  the  lowest  level  C  language  interface  to  the  X  Win 
dow  System.  Both  the  Xt  Intrinsics  and  Xlib  are  required  by  the  X  standard  (established  by 
the  X  Consortium)  on  any  system  that  allows  programming  of  X  applications. 

Xaw  was  developed  by  MIT's  Project  Athena,  and  the  acronym  Xaw  stands  for  Athena  Widg 
ets.  Primarily,  Xaw  was  designed  as  a  simple  demonstration  and  test  of  the  Intrinsics — not 
as  a  complete  set  of  widgets  for  writing  demanding  applications.  There  are  numerous  other 
widget  sets  provided  by  system  vendors  to  implement  particular  user-interface  styles.  The 
two  dominant  widget  sets  are  OSF/Moft/,  which  has  a  user  interface  similar  to  IBM's  Presen 
tation  Manager,  and  AT&T  and  Sun's  OPEN  LOOK  Widget  set 

The  X  Toolkit  Intrinsics  will  work  the  same  way  with  any  of  these  Xt-compatible  widget  sets. 
In  fact,  it  is  possible,  though  not  always  aesthetically  or  economically  desirable,  to  combine 
widgets  from  different  widget  sets  in  the  same  application.* 


*Note  that  there  are  other  X  toolkits  (note  the  lower-case  "t"  in  "toolkits")  that  have  nothing  whatever  to  do  with  the 
X  Toolkit  (Xt),  except  that  they  have  similar  goals — namely,  to  make  it  easier  to  write  standard  X  applications. 
These  toolkits  include  Andrew  (from  Carnegie-Mellon  University),  Interviews  (from  Stanford),  and  XView  (from 
Sun).  These  are  not  merely  different  widget  sets  but  are  entirely  different  toolkits.  They  are  not  compatible  with  Xt. 
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About  This  Book 

This  book  is  the  fifth  volume  in  the  O'Reilly  &  Associates  X  Window  System  Series.  It 
includes  reference  pages  for  each  of  the  Xt  Intrinsics  functions  and  macros,  for  useful  proto 
type  procedures,  for  Intrinsics  classes  and  methods,  and  for  the  Athena  Widgets.  Within  each 
section,  reference  pages  are  organized  alphabetically  for  ease  of  access;  a  permuted  index 
and  numerous  appendices  and  quick  reference  aids  are  also  provided. 

Volumes  Four  and  Five  are  designed  to  be  used  together.  Volume  Four  provides  an  explana 
tion  of  the  X  Toolkit,  including  tutorial  material  and  numerous  programming  examples. 
Arranged  by  task  or  topic,  each  chapter  brings  together  a  group  of  X  Toolkit  functions, 
describes  the  conceptual  foundation  they  are  based  on,  and  illustrates  how  they  are  most 
often  used  in  writing  applications.  This  volume  is  structured  so  as  to  be  useful  as  a  tutorial 
and  also  as  a  task-oriented  reference. 

To  get  the  most  out  of  the  examples  in  Volume  Four,  you  will  need  the  exact  calling 
sequences  of  each  function  from  Volume  Five.  To  understand  fully  how  to  use  each  of  the 
functions  described  in  Volume  Five,  all  but  the  most  experienced  Toolkit  "hacker"  will  need 
the  explanation  and  examples  in  Volume  Four. 

Even  though  the  Toolkit  is  intended  to  hide  the  low-level  X  interface  provided  by  Xlib,  there 
are  times  in  writing  widgets  when  Xlib  functions  will  be  necessary  because  no  Xt  feature 
exists  to  do  the  same  thing.  Volume  Four  describes  the  most  common  occasions  for  using 
Xlib  but  does  not  provide  a  reference  to  the  particular  functions  involved.  For  that,  see  Vol 
ume  One,  Xlib  Programming  Manual,  and  Volume  Two,  Xlib  Reference  Manual. 

How  This  Book  is  Organized 

Volume  Five  consists  of  reference  pages  for  Toolkit  functions.  It  also  contains  numerous 
helpful  appendices.  r, 

The  book  is  organized  as  follows: 

Preface  Describes  the  organization  of  the  book  and  the  conventions  it  follows. 

Introduction        Provides  an  overview  of  the  functional  areas  the  reference  pages  fall  into. 

Permuted  Index  Provides  a  standard  UNIX  permuted  index  for  all  reference  pages,  regardless 
of  section. 

Section  1  Intrinsics  Functions  and  Macros,  contains  reference  pages  for  the  Intrinsics 

functions  and  macros.  The  header  on  each  reference  page  states  whether 
the  function  applies  to  using  or  building  widgets,  but  all  are  organized 
alphabetically. 

Section  2  Prototype  Procedures,  lists  the  prototypes  used  for  declaring  application 

callback  routines,  actions,  widget  methods,  and  other  user-supplied  func 
tions. 
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Section  3  Intrinsics   Classes,  contains   reference   pages   for  the   required   widget 

classes — Core,  Composite,  Constraint,  and  Shell. 

Section  4  Intrinsics  Methods,  contains  reference  pages  for  the  methods  used  by  the 

Intrinsics  classes. 

Section  5  Athena  Classes,  contains  reference  pages  for  the  Athena  classes. 

Appendix  A  Function  Summaries,  provides  quick  reference  tables  that  list  each  Intrin 
sics  function  alphabetically  and  by  logical  groups. 

Appendix  B  X  Toolkit  Data  Types,  lists  and  explains,  in  alphabetical  order,  the  struc 
tures,  enums  and  other  typedefs  used  for  arguments  to  Xt  functions  and 
macros. 

Appendix  C  Event  Reference,  describes  each  event  type  in  a  reference  page  format. 
Each  page  includes  information  on  how  to  select  the  events,  when  they  are 
generated,  the  contents  of  the  event  structures,  and  notes  on  how  to  use 
them. 

Appendix  D  Standard  Errors  and  Warnings,  lists  the  possible  errors  or  warnings 
returned  by  the  X  Toolkit,  along  with  their  possible  cause. 

Appendix  E         Resource  File  Format,  explains  the  EBNF  syntax  used  the  resource  file. 

Appendix  F  Translation  Table  Syntax,  explains  the  EBNF  syntax  used  the  translation 
table.  It  discusses  modifiers  and  event  types. 

Appendix  G        StringsDefs.h  Header  File,  groups  the  identifiers  found  in  StringDefs.h. 

Appendix  H  Release  Notes,  summarizes  a  few  of  the  changes  between  Release  3  and 
Release  4. 

Master  Index  Provides  a  thorough,  combined  index  to  Volumes  Four  and  Five,  making  it 
easy  to  look  up  all  the  appropriate  references  to  a  topic,  in  either  volume. 

Assumptions 

This  book  makes  no  assumptions  about  the  reader's  knowledge  of  object-oriented  program 
ming  or  the  X  Window  System.  However,  for  many  advanced  topics,  the  reader  will  need  to 
consult  the  earlier  volumes  in  this  series — Volume  One,  Xlib  Programming  Manual,  and 
Volume  Two,  Xlib  Reference  Manual. 

Readers  should  be  proficient  in  the  C  programming  language,  although  examples  are  pro 
vided  for  infrequently  used  features  of  the  language  that  are  necessary  or  useful  when  pro 
gramming  with  the  X  Toolkit.  In  addition,  general  familiarity  with  the  principles  of  raster 
graphics  will  be  helpful. 
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Related  Documents 

Seven  other  books  on  the  X  Window  System  are  available  from  O'Reilly  &  Associates,  Inc.: 
Volume  Zero       X  Protocol  Reference  Manual 
Volume  One        Xlib  Programming  Manual 
Volume  Two       Xlib  Reference  Manual 
Volume  Three     X  Window  System  User' s  Guide 
Volume  Four       X  Toolkit  Intrinsics  Programming  Manual 
Volume  Seven     XView  Programming  Manual 
Quick  Reference  The  X  Window  System  in  a  Nutshell 

The  following  documents  are  included  on  the  XI 1  source  tape: 

X  Toolkit  Intrinsics — C Language  Interface,  by  Joel  McCormack,  Paul  Asente, 

and  Ralph  Swick 
X  Toolkit  Athena  Widgets — C  Language  Interface,  by  Ralph  Swick  and 

Terry  Weissman 
Xlib — C  Language  X  Interface,  by  Jim  Getty  s,  Ron  Newman,  and  Robert  Scheifler 

The  following  Nutshell  Handbooks  published  by  O'Reilly  and  Associates,  Inc.  are  useful 
when  programming  in  C: 

Checking  C  Programs  with  lint,  by  Ian  Darwin 
Managing  Projects  with  make,  by  Steve  Talbott 
Using  C  on  the  UNIX  System,  by  Dave  Curry 

The  following  is  the  classic  introduction  to  C  programming: 

The  C  Programming  Language,  by  B.  W.  Kernighan  and  D.  M.  Ritchie 

Conventions  Used  in  This  Book 

Italics  are  used  for: 

•  UNIX  pathnames,  filenames,  program  names,  user  command  names,  and  options  for  user 
commands. 

•  New  terms  where  they  are  defined. 

Typewriter   Font  is  used  for: 

•  Anything  that  would  be  typed  verbatim  into  code,  such  as  examples  of  source  code  and 
text  on  the  screen. 

•  The  contents  of  include  files,  such  as  structure  types,  structure  members,  symbols 
(defined  constants  and  bit  flags),  and  macros. 
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•  Xt  functions. 

•  Names  of  subroutines  of  the  example  programs. 

Italic   Typewriter  Font  is  used  for: 

•  Arguments  to  Xt  functions,  since  they  could  be  typed  in  code  as  shown  but  are  arbitrary 
names  that  could  be  changed. 

Helvetica  Italics  are  used  for: 

•  Titles  of  examples,  figures,  and  tables. 

Boldface  is  used  for: 

•  Chapter  and  section  headings. 


Requests  for  Comments 


Please  write  to  tell  us  about  any  flaws  you  find  in  this  manual  or  how  you  think  it  could  be 
improved  in  order  to  help  us  provide  you  with  the  best  documentation  possible. 

Our  U.S.  mail  address,  e-mail  address,  and  telephone  numbers  are  as  follows: 

O'Reilly  and  Associates,  Inc. 
632  Petaluma  Avenue 
Sebastopol,  CA  95472 
800-338-6887 
international  +1  707-829-0515 

UUCP:  uunetioraltim  ARPA:  tim@ora.com 

Bulk  Sales  Information 

This  manual  is  being  resold  by  many  workstation  manufacturers  as  their  official  X  Window 
System  documentation.  For  information  on  volume  discounts  for  bulk  purchase,  call 
O'Reilly  and  Associates,  Inc.,  at  800-338-6887,  or  send  e-mail  to  linda@ora.com 
(uunet!ora!linda). 

For  companies  requiring  extensive  customization  of  the  book,  source  licensing  terms  are  also 
available. 
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Obtaining  the  X  Window  System  Software 

The  X  Window  System  is  copyrighted  but  freely  distributed.  The  only  restriction  this  places 
on  its  use  is  that  the  copyright  notice  identifying  the  author  and  the  terms  of  use  must  accom 
pany  all  copies  of  the  software  or  documentation.  Thanks  to  this  policy,  the  software  is  avail 
able  for  nominal  cost  from  a  variety  of  sources.  See  Appendix  F,  Sources  of  Additional 
Information,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual,  for  a  listing  of 
these  sources. 
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Overview 


Before  plunging  into  the  five  sections  of  reference  pages,  you  might  benefit 
from  a  review  of  the  Intrinsics.  The  Introduction  provides  this  review,  as  well 
as  describing  how  to  find  the  information  in  the  reference  sections.  The  Per 
muted  Index  can  direct  you  to  a  particular  reference  page  if  you  have  an  idea 
of  what  task  you  need  to  do. 
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Introduction 


The  classic  problem  in  constructing  software  manuals  is  how  to  resolve  the  conflicting  needs 
of  tutorial  and  reference.  Over  time,  we  have  found  that  the  alphabetical  "man  page"* 
approach  of  the  UNIX  Reference  Manual  has  consistently  made  it  the  most  accessible  refer 
ence  manual  we  have  ever  used.  However,  as  has  often  been  pointed  out  by  detractors  of 
UNIX,  this  approach  can  make  the  manual  impenetrable  to  a  novice. 

We  believe  that  the  ideal  solution  is  a  tutorial  manual/reference  manual  pair,  in  which  the 
tutorial  manual  gives  an  understanding  of  the  whole  and  the  alphabetical  reference  manual 
supplies  all  of  the  additional  details.  This  Volume  Five  is  the  reference  manual  that  accom 
panies  Volume  Four,  which  is  tutorial. 

All  X  Consortium  standards  such  as  the  Xt  Intrinsics  are  defined  by  documents,  not  by  any 
sample  code.  The  Intrinsics  specification  is  full  of  details  and  was  primarily  designed  to  help 
expert  programmers  port  or  implement  the  Intrinsics  on  various  systems.  The  specification 
assumes  an  intimate  knowledge  of  the  concepts  with  which  it  was  designed,  many  of  which 
are  not  apparent  to  those  not  involved  in  its  development.  (This  is  especially  so  because  the 
Intrinsics  breaks  new  ground  in  many  areas,  including  user  configurability,  portability,  and 
internationalization  (making  a  program  operable  in  more  than  one  language)).  Nevertheless, 
all  reference  documentation  must  be  based  on  the  specification,  because  it  is  the  definition  of 
the  Intrinsics.  In  order  to  maintain  accuracy  and  remain  faithful  to  the  Xt  specification,  we 
have  included  virtually  all  of  its  text  But  we  have  also  done  as  much  as  possible  to  make  the 
information  more  accessible  and  more  usable  by  non-experts. 

First,  we  have  discreetly  edited  the  reference  material  to  include  more  conceptual  and  con 
textual  material.  We  have  tried  to  provide  enough  context  so  that  you  have  an  idea  of  how 
each  function  is  used,  without  burying  the  important  details  so  much  as  to  delay  access  to 
them.  For  example,  while  discussing  a  prototype  procedure,  we  expand  the  description  pro 
vided  by  the  specification  to  include  a  mention  of  the  function  used  to  register  that  proce 
dure.  We  have  also  added  examples  and  definitions  of  structures  to  many  pages. 

Second,  we  have  added  a  level  of  structure  beyond  alphabetization.  The  manual  is  divided 
into  five  numbered  sections  (plus  this  introduction  and  appendices): 


*That  is,  manual  page — or  reference  page,  as  we'll  call  it. 
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1.  Intrinsics  functions  and  macros  -  these  are  the  functions  used  by  application  writers  and 
by  widget  writers. 

2.  Prototype  procedures  -  these  are  user-defined  or  widget-defined  functions  that  are  regis 
tered  with  the  Intrinsics  using  one  of  the  Intrinsics  functions. 

3.  Intrinsics  classes  -  these  are  the  objects  defined  by  the  Intrinsics,  which  are  the  basis  of 
all  objects  defined  in  widget  sets. 

4.  Intrinsics  methods  -  these  are  the  widget-writer-defined  functions  that  implement  a 
widget.  These  methods  are  defined  by  the  Intrinsics  as  part  of  the  Intrinsics  classes. 

5.  Athena  classes  -  this  is  a  description  of  each  widget  in  the  Athena  widget  set   The 
Athena  set  is  intended  for  demonstration  and  testing  of  the  Intrinsics,  not  for  commercial 
application  development,  but  it  is  useful  for  writing  simple  applications  because  it  is 
widely  available. 

A  few  features  of  the  layout  are  worth  mentioning.  Each  of  the  five  reference  page  sections 
begins  with  an  introductory  page  that  briefly  describes  the  section  and  lists  the  names  of  all 
pages  contained  in  that  section.  The  page  header  includes  the  page  name  and  also  indicates  a 
general  subject  area  for  related  routines,  procedures,  or  methods.  Some  pages  have  a  Struc 
tures  section  that  shows  the  definitions  of  any  types  used  as  arguments  or  returned  by  the 
function  or  prototype  procedure.  Cross-references  to  other  reference  pages  use  a  parentheti 
cal  section  notation — e.g.,  Core(3)  means  the  page  for  Core  can  be  found  in  Section  3. 

The  remainder  of  this  introduction  is  composed  of  the  overview  material  from  the  Xt  specifi 
cation,  following  its  original  organization.  Each  section  begins  with  some  text  introducing  a 
particular  group  of  functions  or  procedure  types,  followed  by  a  list  of  that  group. 


1 .1   Intrinsics  and  Widgets 

The  Intrinsics  (also  referred  to  as  Xt)  and  a  widget  set  make  up  the  X  Toolkit.  The  Intrinsics 
provide  the  base  mechanisms  necessary  to  build  a  wide  variety  of  widget  sets  and  application 
environments.  Because  the  Intrinsics  mask  implementation  details  from  the  widget  program 
mer  and  the  application  programmer,  the  widgets  and  the  application  environments  built  with 
them  are  fully  extensible  and  support  independently  developed,  new  or  extended  compo 
nents.  By  following  a  small  set  of  conventions,  widget  programmers  can  extend  their  widget 
sets  in  new  ways  and  can  have  these  extensions  function  smoothly  with  the  existing  facilities. 

The  Intrinsics  are  a  library  package  layered  on  top  of  Xlib.  As  such,  the  Intrinsics  provide 
mechanisms  (functions  and  structures)  for  extending  the  basic  programming  abstractions  pro 
vided  by  the  X  Window  System. 

A  typical  X  Toolkit  application  is  most  likely  to  be  a  client  of  a  given  widget  set,  a  subset  of 
the  Intrinsics  functions,  and  a  smaller  set  of  Xlib  functions.  At  the  same  time,  a  widget  set  is 
a  client  of  both  the  Intrinsics  and  Xlib,  and  the  Intrinsics  are  a  client  of  Xlib  only. 
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For  the  application  programmer,  the  X  Toolkit  provides: 

•  A  consistent  interface  (widget  set)  for  writing  applications. 

•  A  small  set  of  Intrinsics  mechanisms  that  also  are  used  in  writing  applications. 

For  the  widget  programmer,  the  X  Toolkit  provides: 

•  A  set  of  Intrinsics  mechanisms  for  building  widgets. 

•  An  architectural  model  for  constructing  and  composing  widgets. 

•  A  consistent  interface  (widget  set)  for  programming. 

To  the  extent  possible,  the  X  Toolkit  is  policy  free.  The  application  environment — not  the  X 
Toolkit — defines,  implements,  and  enforces: 

•  Policy 

•  Consistency 

•  Style 

Each  individual  widget  implementation  defines  its  own  policy.  The  X  Toolkit  design  allows 
for  the  development  of  radically  differing  widget  implementations. 

For  related  discussion,  see  the  following  Xt  routines  and  methods: 


XtCheckSubclass(\) 

XtClass(\) 

XtlnitializeWidgetClass  ( 1 ) 

XtIsApplicationShell(\) 

XtlsComposite  ( 1 ) 

XtIsConstraint(\) 

XtIsObject(l) 


XtIsOverrideShell(l) 

XtlsRectObjd) 

XtlsShelld) 

XtIsSubclass(l) 

XtlsTopLevelShell 

XtIsTransientShell(l) 


XtIsVendorShell(l) 
XtIsWidget(\) 
XtlsWMShelld) 
XtSuperclass(\) 
class _init  ialize  (4) 
class _part_initialize  (4) 


1.2  Widget  Instantiation 

A  collection  of  widget  instances  constitutes  a  widget  tree.  The  shell  widget  returned  by  xt  - 
AppCreateShell  is  the  root  of  the  widget  tree  instance.  The  widgets  with  one  or  more 
children  are  the  intermediate  nodes  of  that  tree,  and  the  widgets  with  no  children  of  any  kind 
are  the  leaves  of  a  widget  tree.  With  the  exception  of  pop-up  children,  this  widget  tree 
instance  defines  the  associated  X  Window  tree. 

Widgets  can  be  either  composite  or  primitive.  Both  kinds  of  widgets  can  contain  children, 
but  the  Intrinsics  provide  a  set  of  management  mechanisms  for  constructing  and  interfacing 
between  composite  widgets,  their  children,  and  other  clients. 

Composite  widgets,  subclasses  of  the  Composite  class,  are  containers  for  an  arbitrary  but 
implementation-defined  collection  of  children,  which  may  be  instantiated  by  the  composite 
widget  itself,  by  other  clients,  or  by  a  combination  of  the  two.  Composite  widgets  also 
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contain  methods  for  managing  the  geometry  (layout)  of  any  child  widget  Under  unusual  cir 
cumstances,  a  composite  widget  may  have  zero  children,  but  it  usually  has  at  least  one.  By 
contrast,  primitive  widgets  that  contain  children  typically  instantiate  specific  children  of 
known  class  themselves  and  do  not  expect  external  clients  to  do  so.  Primitive  widgets  also 
do  not  have  general  geometry  management  methods. 

In  addition,  the  Intrinsics  recursively  perform  many  operations  (for  example,  realization  and 
destruction)  on  composite  widgets  and  all  of  their  children.  Primitive  widgets  that  have  chil 
dren  must  be  prepared  to  perform  the  recursive  operations  themselves  on  behalf  of  their  chil 
dren. 

A  widget  tree  is  manipulated  by  several  Intrinsics  functions.  For  example,  XtRealize- 
widget  traverses  the  tree  downward  and  recursively  realizes  all  pop-up  widgets  and  chil 
dren  of  composite  widgets.  XtDestroyWidget  traverses  the  tree  downward  and  destroys 
all  pop-up  widgets  and  children  of  composite  widgets.  The  functions  that  fetch  and  modify 
resources  traverse  the  tree  upward  and  determine  the  inheritance  of  resources  from  a  widget's 
ancestors.  XtMakeGeometryRequest  traverses  the  tree  up  one  level  and  calls  the 
geometry  manager  that  is  responsible  for  a  widget  child's  geometry. 

To  facilitate  up-traversal  of  the  widget  tree,  each  widget  has  a  pointer  to  its  parent  widget. 
The  Shell  widget  that  xtAppCreateShell  returns,  however,  has  a  parent  pointer  of 

NULL. 

To  facilitate  down-traversal  of  the  widget  tree,  each  composite  widget  has  a  pointer  to  an 
array  of  children  widgets,  which  includes  all  normal  children  created,  not  just  the  subset  of 
children  that  are  managed  by  the  composite  widget's  geometry  manager.  Primitive  widgets 
that  instantiate  children  are  entirely  responsible  for  all  operations  that  require  downward 
traversal  below  themselves.  In  addition,  every  widget  has  a  pointer  to  an  array  of  pop-up 
children  widgets. 

1 .2.1    Initializing  the  X  Toolkit 

Before  an  application  can  call  any  of  the  Intrinsics  functions,  it  must  initialize  the  X  Toolkit 
by  using: 

•  xtToolkitlnitialize,  which  initializes  the  X  Toolkit  internals. 

•  xtCreateApplicationContext,  which  initializes  the  per-application  state. 

•  xtDisplaylnitialize  or  xtOpenDisplay,  which  initializes  the  per-display 
state. 

•  XtAppCreateShell,  which  creates  the  initial  widget 

or  by  calling  the  convenience  procedure  xtApplnitialize,  which  combines  the  func 
tions  of  the  preceding  procedures. 

Multiple  instances  of  X  Toolkit  applications  may  be  implemented  in  a  single  address  space. 
Each  instance  needs  to  be  able  to  read  input  and  dispatch  events  independently  of  any  other 
instance.  Further,  an  application  may  need  multiple  display  connections  or  need  to  have 
widgets  on  multiple  screens.  To  accommodate  both  requirements,  the  Intrinsics  define 
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application  contexts,  each  of  which  provides  the  information  needed  to  distinguish  one  appli 
cation  instance  from  another.  The  major  component  of  an  application  context  is  a  list  of  X 
Display  pointers  for  that  application.  The  application  context  type  xtAppContext  is 
opaque  to  clients. 

For  related  discussion,  see  the  following  Xt  routines,  prototype  procedures,  and  methods: 


XtAddCallback(l) 

XtAppCreateShell(l) 

XtAppInitialize(l) 

XtAppSetFallbackResources(l) 

XtCloseDisplay(l) 

XtCreateApplicationContext(\) 

XtCreateWidget(l) 

XtCreateWindo\v(\) 

XtDatabase(l) 

XtDestroyApplicationContext(\) 

XtDestroyWidget^) 

XtDisplayInitialize(\ ) 

XtDisplayOfObject(\) 


XtDisplay(\) 

XtlsRealized(\) 

XtMergeArgLists(l ) 

XtName(\) 

XtOpenDisplay(\) 

XtParent(l) 

XtReaIizeWidget(\) 

XtRemoveCallback(l) 

XtScreenOfObject(\) 

XtScreen(\) 

XtSetArg(l) 

XfToolkitlnitialize  ( 1 ) 

XtUnrealizeWidget(l ) 


XtVaAppCreateShell(\ ) 

XtVaAppInitialize  ( 1 ) 

XtVaCreateArgsList(l ) 

XtVaCreateWidget(\) 

XtWidgetfoApplicationContext  ( 1 ) 

XtWindowOJObject(l) 

XtWindow(l) 

XtCallbackProc(2) 

initialize  (4) 

initialize Jiook  (4) 

realize^) 

destroy (4) 

Constraint  destroy ^(4) 


1.3  Widget  Management 

Composite  widgets  (widgets  that  are  a  subclass  of  compositeWidgetClass)  can  have 
an  arbitrary  number  of  children.  Consequently,  they  are  responsible  for  much  more  than 
primitive  widgets.  Their  responsibilities  (either  implemented  directly  by  the  widget  class  or 
indirectly  by  Intrinsics  functions)  include: 

•  Overall  management  of  children  from  creation  to  destruction. 

•  Destruction  of  descendants  when  the  composite  widget  is  destroyed. 

•  Physical  arrangement  (geometry  management)  of  a  displayable  subset  of  children  (that  is, 
the  managed  children). 

•  Mapping  and  unmapping  of  a  subset  of  the  managed  children. 

Overall  management  is  handled  by  XtCreateWidget  and  XtDestroyWidget.  Xt- 
CreateWidget  adds  children  to  their  parent  by  calling  the  parent's  insert_child 
method.  XtDestroyWidget  removes  children  from  their  parent  by  calling  the  parent's 
delete_child  method  and  ensures  that  all  children  of  a  destroyed  composite  widget  also 
get  destroyed. 

Only  a  subset  of  the  total  number  of  children  is  actually  managed  by  the  geometry  manager 
and,  hence,  possibly  visible.  For  example,  a  multibuffer,  composite  editor  widget  might  allo 
cate  one  child  widget  for  each  file  buffer,  but  it  might  display  only  a  small  number  of  the 
existing  buffers.  Windows  that  are  in  this  displayable  subset  are  called  managed  windows 
and  enter  into  geometry  manager  calculations.  The  other  children  are  called  unmanaged  win 
dows  and,  by  definition,  are  not  mapped. 
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Children  are  added  to  the  managed  set  by  using  XtManageChild  and  XtManage- 
Children;  children  are  removed  from  the  managed  set  by  using  xtUnmanageChild 
and  XtUnmanageChildren.  These  four  functions  notify  the  parent  to  recalculate  the 
physical  layout  of  its  children  by  calling  the  parent's  change_managed  method.  The 
XtCreateManagedWidget  convenience  function  calls  XtCreateWidget  and  Xt 
ManageChild  on  the  result. 

Most  managed  children  are  mapped,  but  some  widgets  can  be  in  a  state  where  they  take  up 
physical  space  but  do  not  show  anything.  Managed  widgets  are  not  mapped  automatically  if 
their  map_when__managed  field  is  False.  The  default  is  True  and  is  changed  by  using 
XtSetMappedWhenManaged. 

For  related  discussion,  see  the  following  Xt  routines,  prototype  procedures,  and  methods: 


XtCreateManagedWidget  ( 1 ) 
XtIsManaged(V) 
XtManageChild(l) 
XtManageChildren  ( 1 ) 
XtMapWidget(l) 


XtSetMappedWhenManaged(\ ) 
XtUnmanageChitd(\) 
XtUnmanageChildren  ( 1 ) 
XtUnmapWidget(l) 
XtVaCreateManagedWidget(l) 


XtOrderProc(T) 
changejnanaged(4) 
delete_child(4) 
insert  child  (4) 


1.4  Shell  Widgets 


Shell  widgets  hold  an  application's  top-level  widgets  to  allow  them  to  communicate  with  the 
window  manager.  Shells  have  been  designed  to  be  as  nearly  invisible  (to  the  programmer)  as 
possible.  Clients  have  to  create  them,  but  they  should  never  have  to  worry  about  their  sizes. 

If  a  shell  widget  is  resized  from  the  outside  (typically  by  a  window  manager),  the  shell 
widget  also  resizes  its  child  widget  automatically.  Similarly,  if  the  shell's  child  widget  needs 
to  change  size,  it  can  make  a  geometry  request  to  the  shell,  and  the  shell  negotiates  the  size 
change  with  the  outer  environment.  Clients  should  never  attempt  to  change  the  size  of  their 
shells  directly. 

The  four  types  of  public  shells  are: 


OverrideShell 


TransientShell 


TopLevelShell 


Applications  hell 


Used  for  shell  windows  that  completely  bypass  the  window  man 
ager  (for  example,  pop-up  menu  shells). 

Used  for  shell  windows  that  have  the  WM_TRANSIENT_FOR  prop 
erty  set  The  effect  of  this  property  depends  on  the  window  man 
ager  being  used. 

Used  for  normal  top-level  windows  (for  example,  any  additional 
top-level  widgets  an  application  needs). 

Used  by  the  window  manager  to  define  a  separate  application 
instance,  which  is  the  main  top-level  window  of  the  application. 
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Widgets  negotiate  their  size  and  position  with  their  parent  widget — that  is,  the  widget  that 
directly  contains  them.  Widgets  at  the  top  of  the  hierarchy  do  not  have  parent  widgets. 
Instead,  they  must  deal  with  the  outside  world.  To  provide  for  this,  the  top  of  every  widget 
tree  is  a  special  widget,  called  a  Shell. 

Shell  widgets,  a  subclass  of  the  Composite  widget,  encapsulate  other  widgets  and  can  allow  a 
widget  to  avoid  the  geometry  clipping  imposed  by  the  parent/child  window  relationship. 
They  also  can  provide  a  layer  of  communication  with  the  window  manager. 

For  related  discussion,  see  the  following  Intrinsics  classes: 

ApplicationShell(3)  Transients  hell  (3) 

OverfideShellQ)  Vendor Shell  (3) 

Shell(3)  WMShellQ) 
TopLevelShell(3) 


1.5  Pop-Up  Widgets 

Pop-up  widgets  are  used  to  create  windows  that  are  outside  of  the  window  hierarchy  defined 
by  the  widget  tree.  To  prevent  a  pop-up  window  from  being  clipped  by  the  pop-up  widget's 
parent  window,  each  pop-up  child  has  a  window  that  is  a  descendant  of  the  root  window. 
This  means  that  pop-ups  differ  from  normal  widget  children  in  the  way  they  are  created  and 
attached  to  their  widget  parent 

A  parent  of  a  pop-up  widget  does  not  actively  manage  its  pop-up  children;  in  fact,  it  usually 
never  notices  them  or  operates  upon  them.  The  popup_list  field  in  the  CorePart 
structure  contains  the  list  of  its  pop-up  children.  This  pop-up  list  exists  mainly  to  provide  the 
proper  place  in  the  widget  hierarchy  for  the  pop-up  to  get  resources  and  to  provide  a  place  for 
XtDestroyWidget  to  look  for  all  extant  children. 

A  Composite  widget  can  have  both  normal  children  and  pop-up  children.  A  pop-up  widget 
can  be  popped  up  from  almost  anywhere,  not  just  from  its  parent  A  child  always  refers  to  a 
normal,  geometry-managed  child  on  the  children  list,  whereas  a  pop-up  child  always  refers  to 
a  child  on  the  pop-up  list. 


1 .5.1    Pop-Up  Widget  Types 

There  are  three  kinds  of  pop-up  widgets: 

•  A  modeless  pop  up  (for  example,  a  modeless  dialog  box)  is  usually  visible  to  the  window 
manager  and  looks  like  any  other  application  from  the  user's  point  of  view.  (The  applica 
tion  itself  is  a  special  form  of  a  modeless  pop  up.) 

•  A  modal  pop  up  (for  example,  a  modal  dialog  box)  may  or  may  not  be  visible  to  the  win 
dow  manager  and,  except  for  events  that  occur  in  the  dialog  box,  disables  user-event  pro 
cessing  by  the  application. 


Introduction 


•  A  spring-loaded  pop  up  (for  example,  a  menu)  is  usually  not  visible  to  the  window  man 
ager  and,  except  for  events  that  occur  in  the  pop-up  or  its  descendants,  disables  user- 
event  processing  by  all  applications. 

Modal  pop  ups  and  spring-loaded  pop  ups  are  similar  and  should  be  coded  as  if  they  were  the 
same.  In  fact,  the  same  widget  (for  example,  a  ButtonBox  or  Menu)  can  be  used  both  as  a 
modal  pop  up  and  as  a  spring-loaded  pop  up  within  the  same  application.  The  main  differ 
ence  is  that  spring-loaded  pop  ups  are  brought  up  with  the  pointer  and,  because  of  the  grab 
that  the  pointer  button  causes,  require  different  processing  by  the  Intrinsics.  Further,  all  user- 
input  remap  events  occurring  outside  the  spring-loaded  pop  up  (e.g.,  in  a  descendant)  are  also 
delivered  to  the  spring-loaded  pop  up  after  they  have  been  dispatched  to  the  appropriate 
descendant  so  that,  for  example,  a  "button  up"  event  can  take  down  a  spring-loaded  pop-up 
no  matter  where  the  button  up  occurs. 

Any  kind  of  pop  up,  in  turn,  can  pop  up  other  widgets.  Modal  and  spring-loaded  pop  ups  can 
constrain  user  events  to  the  most  recent  such  pop  up  or  to  any  of  the  modal/spring-loaded  pop 
ups  currently  mapped. 

Regardless  of  their  type,  all  pop-up  widget  classes  are  responsible  for  communicating  with 
the  window  manager  and,  therefore,  are  subclasses  of  Shell. 

For  related  discussion,  see  the  following  Xt  routines: 

XtCallbackExclusive(l)  XtCallbackPopdown(l)       XtPopupSpringLoaded(l) 

XtCallbackNone(l)  XtCreatePopupShell(l)       XtPopupd) 

XtCallbackNonexclusive(\)       XtPopdown(l)  XtVaCreatePopupShell(l) 


1.6  Geometry  Management 


A  widget  does  not  directly  control  its  size  and  location;  rather,  its  parent  is  responsible  for 
controlling  its  size  and  location.  Although  the  position  of  children  is  usually  left  up  to  their 
parent,  the  widgets  themselves  often  have  the  best  idea  of  their  optimal  sizes  and,  possibly, 
preferred  locations. 

Each  composite  widget  class  has  a  geometry  manager,  which  is  responsible  for  figuring  out 
where  the  managed  children  should  appear  within  the  composite  widget's  window.  To 
resolve  physical  layout  conflicts  between  sibling  widgets  and  between  a  widget  and  its  par 
ent,  the  Intrinsics  provide  the  geometry  management  mechanism.  Almost  all  Composite 
widgets  have  a  geometry  manager  (geometry_manager  field  in  the  widget  class  record) 
that  is  responsible  for  the  size,  position,  and  stacking  order  of  the  widget's  children.  The 
only  exception  are  fixed  boxes,  which  create  their  children  themselves  and  can  ensure  that 
their  children  will  never  make  a  geometry  request 

Geometry  management  techniques  fall  into  four  classes: 

1.   Fixed  boxes  have  a  fixed  number  of  children  that  are  created  by  the  parent  All  of  these 
children  are  managed,  and  none  ever  make  geometry  manager  requests. 
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2.  Homogeneous  boxes  treat  all  children  equally  and  apply  the  same  geometry  constraints  to 
each  child.  Many  clients  insert  and  delete  widgets  freely. 

3.  Heterogeneous  boxes  have  a  specific  location  where  each  child  is  placed.  This  location 
usually  is  not  specified  in  pixels,  because  the  window  may  be  resized,  but  is  expressed 
rather  in  terms  of  the  relationship  between  a  child  and  the  parent  or  between  the  child  and 
other  specific  children.  Heterogeneous  boxes  are  usually  subclasses  of  Constraint. 

4.  Shell  boxes  have  only  one  child,  which  is  exactly  the  size  of  the  shell.  The  geometry 
manager  must  communicate  with  the  window  manager  if  it  exists,  and  the  box  must  also 
accept  Conf  igureNotify  events  when  the  window  size  is  changed  by  the  window 
manager. 


1.6.1    Initiating  Geometry  Changes 

Parents,  children,  and  clients  all  initiate  geometry  changes  differently.  Because  a  parent  has 
absolute  control  of  its  children's  geometry,  it  changes  the  geometry  directly  by  calling  xt- 
MoveWidget,  XtResizeWidget,  or  XtConfigureWidget.  A  child  must  ask  its 
parent  for  a  geometry  change  by  calling  XtMakeGeometryRequest  or  xtMake- 
ResizeRequest  to  convey  its  wishes  to  its  parent  An  application  or  other  client  code 
initiates  a  geometry  change  by  calling  xtSetValues  on  the  appropriate  geometry  fields, 
thereby  giving  the  widget  the  opportunity  to  do  two  things: 

•  Modify  or  reject  the  client  request  before  it  gets  propagated  to  the  parent 

•  Respond  appropriately  to  the  parent's  reply. 

When  a  widget  that  needs  to  change  its  size,  position,  border  width,  or  stacking  depth  asks  its 
parent's  geometry  manager  to  make  the  desired  changes,  the  geometry  manager  can  do  one 
of  the  following: 

•  Allow  the  request 

•  Disallow  the  request 

•  Suggest  a  compromise. 

When  the  geometry  manager  is  asked  to  change  the  geometry  of  a  child,  the  geometry  man 
ager  may  also  rearrange  and  resize  any  or  all  of  the  other  children  that  it  controls.  The  geom 
etry  manager  can  move  children  around  freely  using  xtMoveWidget.  When  it  resizes  a 
child  (that  is,  when  it  changes  width,  height,  or  border_width)  other  than  the  one 
making  the  request  the  geometry  manager  should  do  so  by  calling  XtResizeWidget.  It 
can  simultaneously  move  and  resize  a  child  with  a  single  call  to  XtConfigureWidget. 

Often,  geometry  managers  find  that  they  can  satisfy  a  request  only  if  they  can  reconfigure  a 
widget  that  they  do  not  control  (in  particular,  when  the  Composite  widget  wants  to  change  its 
own  size).  In  this  case,  the  geometry  manager  makes  a  request  to  its  parent's  geometry  man 
ager.  Geometry  requests  can  cascade  this  way  to  arbitrary  depth. 
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Because  such  cascaded  arbitration  of  widget  geometry  can  involve  extended  negotiation, 
windows  are  not  actually  allocated  to  widgets  at  application  startup  until  all  widgets  are 
satisfied  with  their  geometry. 

For  related  discussion,  see  the  following  Xt  routines,  prototype  procedures,  and  methods: 

XtConfigureWidget(l)  XtResizeWidget(\)  geometry  jnanager  (4) 

XtMakeGeometryRequest  ( 1 )  XtResizeWindow  ( 1 )  resize  (4) 

XtMoveWidget(\)  X (Geometry Handler (2)  query  _geometry($) 
XtQueryGeometry  (1 ) 


1.7  Event  Management 

Whereas  X  allows  the  reading  and  processing  of  events  anywhere  in  an  application,  widgets 
in  the  X  Toolkit  neither  directly  read  events  nor  grab  the  server  or  pointer.  Widgets  register 
procedures  that  are  to  be  called  when  an  event  or  class  of  events  occurs  in  that  widget 

A  typical  application  consists  of  startup  code  followed  by  an  event  loop  that  reads  events  and 
dispatches  them  by  calling  the  procedures  that  widgets  have  registered.  The  default  event 
loop  provided  by  the  Intrinsics  is  XtAppMainLoop. 

The  event  manager  is  a  collection  of  functions  to  perform  the  following  tasks: 

•  Add  or  remove  event  sources  other  than  X  server  events  (in  particular,  timer  interrupts 
and  file  input). 

•  Query  the  status  of  event  sources. 

•  Add  or  remove  procedures  to  be  called  when  an  event  occurs  for  a  particular  widget. 

•  Enable  and  disable  the  dispatching  of  user-initiated  events  (keyboard  and  pointer  events) 
for  a  particular  widget. 

•  Constrain  the  dispatching  of  events  to  a  cascade  of  pop-up  widgets. 

•  Call  the  appropriate  set  of  procedures  currently  registered  when  an  event  is  read. 

Most  widgets  do  not  need  to  call  any  of  the  event  handler  functions  explicitly.  The  normal 
interface  to  X  events  is  through  the  higher-level  translation  manager,  which  maps  sequences 
of  X  events  (with  modifiers)  into  procedure  calls.  Applications  rarely  use  any  of  the  event 
manager  routines  besides  XtAppMainLoop. 

1.7.1    Adding  and  Deleting  Additional  Event  Sources 

Whereas  most  applications  are  driven  only  by  X  events,  some  applications  need  to  incorpo 
rate  other  sources  of  input  into  the  X  Toolkit  event  handling  mechanism.  The  event  manager 
provides  routines  to  integrate  into  this  mechanism  the  notification  of: 
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•  Timer  events 

•  File  data  pending. 

There  are  Intrinsics  functions  that  provide  input  gathering  from  files.  The  application  regis 
ters  the  files  with  the  Intrinsics  read  routine.  When  input  is  pending  on  one  of  the  files,  the 
registered  callback  procedures  are  invoked. 

For  related  discussion,  see  the  following  Xt  routines  and  prototype  procedures: 

XtAppAddInput(\) 
XtRemoveInput(l) 
XtlnputCallbackProc  (2) 

The  timeout  facility  notifies  the  application  or  the  widget  through  a  callback  procedure  that  a 
specified  time  interval  has  elapsed.  Timeout  values  are  uniquely  identified  by  an  interval  ID. 

For  related  discussion,  see  the  following  Xt  routines  and  prototype  procedures: 

XtAppAddTimeOut(l) 
XtRemoveTimeOut(\) 
XtTimerCallbackProc  (2) 


1.7.2   Constraining  Events  to  a  Cascade  of  Widgets 

Modal  widgets  are  widgets  that,  except  for  the  input  directly  to  them,  lock  out  user  input  to 
the  application. 

When  a  modal  menu  or  modal  dialog  box  is  popped  up  using  Xt  Popup,  user  events  (key 
board  and  pointer  events)  that  occur  outside  the  modal  widget  should  be  delivered  to  the 
modal  widget  or  should  be  ignored.  In  no  case  will  user  events  be  delivered  to  a  widget  out 
side  the  modal  widget. 

To  create  a  pop-up  cascade,  menus  can  pop  up  submenus,  and  dialog  boxes  can  pop  up  fur 
ther  dialog  boxes.  In  this  case,  user  events  may  be  delivered  to  one  of  several  modal  widgets 
in  the  cascade. 

Display-related  events  should  be  delivered  outside  the  modal  cascade  so  that  expose  events 
and  the  like  keep  the  application's  display  up  to  date.  Any  event  that  occurs  within  the  cas 
cade  is  delivered  as  usual.  User  events  that  are  delivered  to  the  most  recent  spring-loaded 
shell  in  the  cascade  when  they  occur  outside  the  cascade  are  called  remap  events.  These 
events  are  KeyPress,  KeyRelease,  ButtonPress,  and  ButtonRelease.  User 
events  that  are  ignored  when  they  occur  outside  the  cascade  are  MotionNotify  and 
EnterNotif  y.  All  other  events  are  delivered  normally.  In  particular,  note  that  this  is  one 
way  in  which  widgets  can  receive  LeaveNotif y  events  without  first  receiving  Enter- 
Notify  events;  they  should  be  prepared  to  deal  with  this,  typically  by  ignoring  the 
unmatched  LeaveNot  if  y  events. 

Xt  Popup  uses  the  xtAddGrab  and  xtRemoveGrab  functions  to  constrain  user  events 
to  a  modal  cascade  and  subsequently  to  remove  a  grab  when  the  modal  widget  goes  away. 
Usually  you  should  have  no  need  to  call  them  explicitly. 
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The  Intrinsics  provide  a  set  of  key  grab  and  button  grab  interfaces  that  are  parallel  to  those 
provided  by  Xlib  and  that  allow  the  Intrinsics  to  modify  event  dispatching  when  necessary. 
X  Toolkit  applications  and  widgets  that  need  to  passively  grab  keys  or  buttons  should  use 
these  Intrinsics  routines  rather  than  the  corresponding  Xlib  routines. 

For  related  discussion,  see  the  following  Xt  routines: 

XtAddGrab(\)  XtGrabPointer(l)  XtUngrabKey(\) 

XtGrabButton(l)  XtRemoveGrab(\)  XtUngrabKeyboard(l) 

XtGrabKey(\)  XtUngrabButton(\)  XtUngrabPointer(l) 
XtGrabKeyboard(l) 


1.7.3   Reading  and  Dispatching  Events 

The  event  manager  provides  functions  to  examine  and  read  events  (including  file  and  timer 
events)  that  are  in  the  queue.  These  functions  are  equivalents  of  the  Xlib  calls  XPending, 
XPeekEvent,  and  XNextEvent. 

The  Intrinsics  provide  functions  that  dispatch  events  to  widgets  or  other  application  code. 
Every  client  interested  in  X  events  on  a  widget  uses  1)  xtAddEvent Handler  to  register 
which  events  it  is  interested  in  and  2)  a  procedure  (event  handler)  to  be  called  when  the  event 
happens  in  that  window.  The  translation  manager  automatically  registers  event  handlers  for 
widgets  that  use  translation  tables. 

For  related  discussion,  see  the  following  Xt  routines: 

XtAppMainLoop  ( 1 )        XtAppP  ending  ( 1 ) 
XtAppNextEvent  ( 1 )        XtAppProcessEvent  ( 1 ) 
XtAppP  eekEvent(\ )       XtBuildEventMask(l) 


1.7.4   Setting  and  Checking  a  Widget's  Sensitivity 

Many  widgets  have  a  mode  in  which  they  assume  a  different  appearance  (for  example,  are 
greyed  out  or  stippled),  do  not  respond  to  user  events,  and  become  dormant. 

When  dormant,  a  widget  is  considered  to  be  insensitive.  If  a  widget  is  insensitive,  the  event 
manager  does  not  dispatch  any  events  to  the  widget  with  an  event  type  of  KeyPress,  Key- 
Release,  ButtonPress,  ButtonRelease,  MotionNotify,  EnterNotify, 
LeaveNotif  y,  Focusln,  or  FocusOut. 

A  widget  can  be  insensitive  because  its  sensitive  field  is  False  or  because  one  of  its 
ancestors  is  insensitive  and  thus,  the  widget's  ancestor_sensitive  field  also  is 
False.  A  widget  can  but  does  not  need  to  distinguish  these  two  cases  visually. 

For  related  discussion,  see  the  following  Xt  routines: 

XtCallAcceptFocus(\)  XtSetKeyboardFocus(l) 

XtIsSensitive(l)  XtSetSensitive(l) 
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1.7.5   Adding  Background  Work  Procedures 

The  Intrinsics  have  limited  support  for  background  processing.  Because  most  applications 
spend  most  of  their  time  waiting  for  input,  you  can  register  an  idle-time  work  procedure  that 
will  be  called  when  the  Toolkit  would  otherwise  block  in  XtAppNextEvent  or  xtApp- 
ProcessEvent. 

For  related  discussion,  see  the  following  Xt  routines  and  prototype  procedures: 

XtAppAddWorkProc(\) 
XtRemoveWorkProc(\)          XtWorkProc(2) 


1.7.6  Widget  Exposure 

Every  primitive  widget  and  some  composite  widgets  display  data  on  the  screen  by  means  of 
raw  Xlib  calls.  Widgets  cannot  simply  write  to  the  screen  and  then  forget  what  they  have 
done.  They  must  keep  enough  state  to  redisplay  the  window  or  parts  of  it  if  a  portion  is 
obscured  and  then  re-exposed. 

For  related  discussion,  see  the  following  Xt  method: 
expose  (4) 

1.7.7  X  Event  Handlers 

Event  handlers  are  procedures  that  are  called  when  specified  events  occur  in  a  widget.  Most 
widgets  need  not  use  event  handlers  explicitly.  Instead,  they  use  the  Intrinsics  translation 
manager. 

For  related  discussion,  see  the  following  Xt  routines  and  prototype  procedures: 

XtAddEventHandler(\)  XtInsertRawEventHandler(\)          XtEventHandler(2) 

XtAddRawEventHandler  ( 1 )       XtRemoveEventHandler  ( 1 ) 
XtlnsertEventHandler  ( 1 )  XtRemoveRawEventHandler  ( 1 ) 


1.8  Callbacks 


Applications  and  other  widgets  (clients)  often  need  to  register  a  procedure  with  a  widget  that 
gets  called  under  certain  conditions.  For  example,  when  a  widget  is  destroyed,  every  proce 
dure  on  the  widget's  destroy_callbacks  list  is  called  to  notify  clients  of  the  widget's 
impending  doom. 

Every  widget  has  a  destroy_callbacks  list.  Widgets  can  define  additional  callback 
lists  as  they  see  fit.  For  example,  the  Command  widget  has  a  callback  list  to  notify  clients 
when  the  button  has  been  activated. 
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Except  where  otherwise  noted,  it  is  the  intent  that  all  Intrinsics  functions  may  be  called  at 
any  time,  including  from  within  callback  procedures,  action  routines  and  event  handlers. 

Whenever  a  widget  contains  a  callback  list  for  use  by  clients,  it  also  exports  in  its  public  .h 
file  the  resource  name  of  the  callback  list.  Applications  and  client  widgets  never  access  call 
back  list  fields  directly.  Instead,  they  always  identify  the  desired  callback  list  by  using  the 
exported  resource  name.  All  the  callback  manipulation  functions  listed  in  this  section  check 
to  see  that  the  requested  callback  list  is  indeed  implemented  by  the  widget. 

For  related  discussion,  see  the  following  Xt  routines  and  prototype  procedures: 

XtAddCallback(l)  XtCallCallbacks(l)  XtRemoveCallback(l) 

XtAddCallbacks(l)  XtHasCallbacks(\)  XtRemoveCallbacks(\) 

XtCallCallbackList(\)       XtRemoveAllCallbacks(\)       XtCallbackProc(2~) 


1.9  Resource  Management 

A  resource  is  a  field  in  the  widget  record  with  a  corresponding  resource  entry  in  the  resource 
list  of  the  widget  or  any  of  its  superclasses.  This  means  that  the  field  is  sellable  by  xt  - 
CreateWidget  (by  naming  the  field  in  the  argument  list),  by  an  entry  in  the  default 
resource  files  (by  using  either  the  name  or  class),  and  by  xtSetValues.  In  addition,  it  is 
readable  by  xt  Get  Values.  Not  all  fields  in  a  widget  record  are  resources.  Some  are  for 
bookkeeping  use  by  the  generic  routines  (like  managed  and  being_destroyed).  Others  can  be 
for  local  bookkeeping,  and  still  others  are  derived  from  resources  (many  graphics  contexts 
and  pixmaps). 

Writers  of  widgets  need  to  obtain  a  large  set  of  resources  at  widget  creation  time.  Some  of 
the  resources  come  from  the  argument  list  supplied  in  the  call  to  xtCreateWidget,  some 
from  the  resource  database,  and  some  from  the  internal  defaults  specified  for  the  widget. 
Resources  are  obtained  first  from  the  argument  list,  then  from  the  resource  database  for  all 
resources  not  specified  in  the  argument  list,  and  lastly  from  the  internal  default,  if  needed. 

For  related  discussion,  see  the  following  Xt  routines  and  methods: 

XtDisplayToApplicationContext(\)  XtSetValues(l)  get_values_hook(4) 

XtGetApplicationResources(l)  XtVaGetApplicationResources(\)  set_yalues(A) 

XtGetValues(l)  XtVaGetValues(l)  set_vatues_almost(4) 

XtOffset(\)  XtVaSetValues(l)  set_values_hook(4) 

XtOffsetOf(  1 )  Constraint  set_values  (4) 
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1.9.1    Resource  Lists 

A  resource  entry  specifies  the  following: 

•  A  field  in  the  widget. 

•  The  textual  name  and  class  of  the  field  that  argument  lists  and  external  resource  files  use 
to  refer  to  the  field. 

•  A  default  value  that  the  field  should  get  if  no  value  is  specified. 
The  declaration  for  the  xtResource  structure  is  as  follows: 

typedef  struct  { 

String  resource_name; 

String  resource_class; 

String  resource_type; 

Cardinal  resource_size; 

Cardinal  resource_of f set; 

String  def ault_type; 

XtPointer  def ault_addr; 
}  XtResource,  *XtResourceList ; 

For  related  discussion,  see  the  following  Xt  routines  and  Athena  class: 

XtGetConstraintResourceList  ( 1 ) 
XtGetResowrceList(\ ) 
Template  (5) 


1.9.2   Resource  Types 

The  resource_type  field  is  the  physical  representation  type  of  the  resource.  By  conven 
tion,  it  starts  with  an  upper-case  letter  and  is  spelled  identically  to  the  type  name  of  the  field. 
The  resource  type  is  used  when  resources  are  fetched  to  convert  from  the  resource  database 
format  (usually  String)  or  the  default  resource  format  (almost  anything,  but  often  String)  to 
the  desired  physical  representation.  The  Intrinsics  define  the  following  resource  types: 


Resource  Type 


XtRAcceleratorTable 

XtRAtom 

XtRBitmap 

XtRBoolean 

XtRBool 

XtRCallback 

XtRCardinal 

XtRColor 

XtRColormap 

XtRCursor 

XtRDimension 

XtRDisplay 


Structure  or  Field  Type 


Xt Accelerators 

Atom 

Pixmap,  depth=l 

Boolean 

Bool 

XtCallbackList 

Cardinal 

XColor 

Colormap 

Cursor 

Dimension 

Display  * 
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Resource  Type 


Structure  or  Field  Type 


XtREnum 

XtRFile 

XtRFloat 

XtRFont 

XtRFontStruct 

XtRFunction 

XtRGeometry 

XtRInitialState 

XtRInt 

XtRLongBoolean 

XtRObject 

XtRPixel 

XtRPixmap 

XtRPointer 

XtRPosition 

XtRScreen 

XtRShort 

XtRString 

XtRStringArray 

XtRStringTable 

XtRTranslationTable 

XtRUnsignedChar 

XtRVisual 

XtRWidget 

XtRWidgetClass 

XtRWidgetList 

XtRWindow 


XtEnum 
FILE* 
float 
Font 

XFontStruct  * 
<*)  () 

char*,  format  as  defined 

by  XParseGeometry 
int 
int 
long 
Object 
Pixel 
Pixmap 
Pointer 
Position 
Screen  * 
short 
char* 
String  * 
char** 

Xt Translations 
unsigned  char 
Visual  * 
Widget 
WidgetClass 
WidgetList 
Window 


1.9.3   Subresources 

A  widget  does  nothing  to  get  its  own  resources;  instead,  xtCreateWidget  does  this  auto 
matically  before  calling  the  class_initialize  method.  Some  widgets  have  subparts 
that  are  not  widgets  but  for  which  the  widget  would  like  to  fetch  resources. 

For  related  discussion,  see  the  following  Xt  routines: 

XtGetSubresources  ( 1 )       XtVaGetSubresources  ( 1 ) 
XtGetSubvalues(\)  XtVaGetSubvaiues(l) 

XtSetSubvalues  ( 1 )  XtVaSetSubvalues  ( 1 ) 
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1.9.4    Resource  Conversions 

The  Intrinsics  provide  a  mechanism  for  registering  representation  converters  that  are  auto 
matically  invoked  by  the  resource  fetching  routines.  The  Intrinsics  additionally  provide  and 
register  several  commonly  used  converters.  This  resource  conversion  mechanism  serves  sev 
eral  purposes: 

•  It  permits  user  files  and  application  resource  files  to  contain  ASCII  representations  of  non 
textual  values. 

•  It  allows  textual  or  other  representations  of  default  resource  values  that  depend  on  the 
display,  screen,  or  colormap,  and  thus  must  be  computed  at  run  time. 

•  It  caches  all  conversion  source  and  result  data.  Conversions  that  require  much  computa 
tion  or  space  (for  example,  string-to-translation  table)  or  that  require  round  trips  to  the 
server  (for  example,  string-to-font  or  -color)  are  performed  only  once. 

For  related  discussion,  see  the  following  Xt  routines  and  prototype  procedures: 


XtAppSe(TypeConverter(\) 
XtAppReleaseCacheRefs  ( 1 ) 
XtCallbackReleaseCacheRefd) 
XtCallbackReleaseCacheReJList  ( 1 ) 


XtCallConverter(l) 
XtConvertAndStore  ( 1 ) 
XtSetfypeConverter  ( 1 ) 
XtConvertArgProc  (2) 


XtDestructor(2) 
XtResourceDefaultProc  (2) 
XfTypeConverter  (2) 


1.10  Translation  Management 

Except  under  unusual  circumstances,  widgets  do  not  hardwire  the  mapping  of  user  events 
into  widget  behavior  by  using  the  event  manager.  Instead,  they  provide  a  default  mapping  of 
events  into  behavior  that  the  user  can  override. 

The  translation  manager  provides  an  interface  to  specify  and  to  manage  the  mapping  of  X 
Event  sequences  into  widget-supplied  functionality — for  example,  calling  procedure  Abe 
when  the  y  key  is  pressed. 

The  translation  manager  uses  two  kinds  of  tables  to  perform  translations: 

•  The  action  tables,  which  are  in  the  widget  class  structure,  specify  the  mapping  of  exter 
nally  available  procedure  name  strings  to  the  corresponding  procedure  implemented  by 
the  widget  class. 

•  A  translation  table,  which  is  in  the  widget  class  structure,  specifies  the  mapping  of  event- 
sequence-to-procedure-name  strings. 

You  can  override  the  translation  table  in  the  class  structure  for  a  specific  widget  instance  by 
supplying  a  different  translation  table  for  the  widget  instance.  The  resource  name  is  xt- 
Ntranslations. 
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1.10.1    Action  Tables 

All  widget  class  records  contain  an  action  table.  In  addition,  an  application  can  register  its 
own  action  tables  with  the  translation  manager  so  that  the  translation  tables  it  provides  to 
widget  instances  can  access  application  functionality. 

For  related  discussion,  see  the  following  Xt  routines  and  prototype  procedures: 

XtAppAddActions(\)  XtActionProc(2) 

XtGetActionKeysym  ( 1 )  XtCallActionProc  (2) 

XtRegisterGrabAction(l) 


1 .1 0.1 .1    Action  Names  to  Procedure  Translations 

The  translation  manager  uses  a  simple  algorithm  to  convert  the  name  of  a  procedure  specified 
in  a  translation  table  into  the  actual  procedure  specified  in  an  action  table.  When  the  widget 
is  realized,  the  translation  manager  performs  a  search  for  the  name  in  the  following  tables,  in 
order: 

•  The  widget's  class  and  all  superclass  action  tables,  in  subclass-to-superclass  order. 

•  The  parent's  class  and  all  superclass  action  tables,  in  subclass-to-superclass  order,  then  on 
up  the  instance  hierarchy  chain. 

•  The  action  tables  registered  with  xtAppAddActions  and  xtAddActions  (from  the 
most  recently  added  table  to  the  oldest  table). 

As  soon  as  it  finds  a  name,  the  translation  manager  stops  the  search.  If  it  cannot  find  a  name, 
the  translation  manager  generates  a  warning  message. 


1.10.2   Action  Hooks 

An  application  can  specify  a  procedure  that  is  called  just  before  every  action  routine  is 
dispatched  by  the  translation  manager. 

For  related  discussion,  see  the  following  Xt  routines  and  prototype  procedures: 

XtAppAddActionHook(\ ) 
XtRemoveActionHook(\ ) 
XtActionHookProc  (2) 


1.10.3  Translation  Tables 

All  widget  instance  records  contain  a  translation  table,  which  is  a  resource  with  no  default 
value.  A  translation  table  specifies  what  action  procedures  are  invoked  for  an  event  or  a 
sequence  of  events.  A  translation  table  is  a  string  containing  a  list  of  translations  from  an 
event  sequence  into  one  or  more  action  procedure  calls.  The  translations  are  separated  from 
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one  another  by  newline  characters  (ASCII  LF).  The  complete  syntax  of  translation  tables  is 
specified  in  Appendix  F,  Translation  Table  Syntax. 

As  an  example,  the  default  behavior  of  Command  is: 

•  Highlight  on  enter  window. 

•  Unhighlight  on  exit  window. 

•  Invert  on  left  button  down. 

•  Call  callbacks  and  reinvert  on  left  button  up. 


1.10.4   Translation  Table  Management 

Sometimes  an  application  needs  to  destructively  or  nondestructively  add  its  own  translations 
to  a  widget's  translation.  For  example,  a  window  manager  provides  functions  to  move  a  win 
dow.  It  usually  may  move  the  window  when  any  pointer  button  is  pressed  down  in  a  title  bar, 
but  it  allows  the  user  to  specify  other  translations  for  the  middle  or  right  button  down  in  the 
title  bar,  and  it  ignores  any  user  translations  for  left  button  down. 

To  accomplish  this,  the  window  manager  first  should  create  the  title  bar  and  then  should 
merge  the  two  translation  tables  into  the  title  bar's  translations.  One  translation  table  con 
tains  the  translations  that  the  window  manager  wants  only  if  the  user  has  not  specified  a 
translation  for  a  particular  event  (or  event  sequence).  The  other  translation  table  contains  the 
translations  that  the  window  manager  wants  regardless  of  what  the  user  has  specified. 

For  related  discussion,  see  the  following  Xt  routines: 

XtA  ugmenfTranslations  ( 1 )        XtParseTranslationTable  ( 1 ) 
XtOverrideTranslations(\)       XtUninstallTranslations(\ ) 


1.10.5   Using  Accelerators 

It  is  often  convenient  to  be  able  to  bind  events  in  one  widget  to  actions  in  another.  In  particu 
lar,  it  is  often  useful  to  be  able  to  invoke  menu  actions  from  the  keyboard.  The  Intrinsics  pro 
vide  a  facility,  called  accelerators,  that  let  you  accomplish  this.  An  accelerator  table  is  a 
translation  table  that  is  bound  with  its  actions  in  the  context  of  a  particular  widget,  the 
"source  widget"  The  accelerator  table  can  then  be  installed  on  one  or  more  destination 
widgets.  When  an  event  sequence  in  the  destination  widget  would  cause  an  accelerator 
action  to  be  taken,  and  if  the  source  widget  is  sensitive,  the  actions  are  executed  as  though 
triggered  by  the  same  event  sequence  in  the  accelerator  source  widget  The  event  is  passed 
to  the  action  procedure  without  modification.  The  action  procedures  used  within  accelerators 
must  not  assume  that  the  source  widget  is  realized,  nor  that  any  fields  of  the  event  are  in  ref 
erence  to  the  source  widget's  window  if  the  widget  is  realized. 
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For  related  discussion,  see  the  following  Xt  routines  and  method: 

XtInstallAccelerators(l )  XtParseAcceleratorTable  ( 1 ) 

XtlnstallAllAccelerators  ( 1 )        display  _accelerator  (4) 


1.10.6   Keyboard  Interpretation 

The  translation  manager  supports  the  automatic  translation  of  keycodes  (from  incoming  key 
events)  into  keysyms.  It  also  allows  the  programmer  to  modify  this  translation  by  providing 
translator  functions. 

For  related  discussion,  see  the  following  Xt  routines  and  prototype  procedures: 

XtConvertCase(l)  XtRegisterCaseConverter(\)       XtCaseProc(2) 

XtGetKeysymTable(\)  XtSetKeyTranslator(\)  XtKeyProc(2) 

XtKeysymToKeycodeList  ( 1 )       XfTranslateKeycode  ( 1 ) 


1.10.7    Multi-click  Time 

Translation  table  entries  may  specify  actions  that  are  taken  when  two  or  more  identical 
events  occur  consecutively,  separated  by  a  short  time  interval  called  the  multi-click  time. 
The  multi-click  time  value  may  be  specified  as  an  application  resource.  If  no  value  is  speci 
fied,  the  initial  value  is  200  milliseconds. 

For  related  discussion,  see  the  following  Xt  routines: 

XtGetMultiClickTime(\ ) 
XtSetMultiClickTime  (1 ) 


1.11   Utility  Functions 

The  Intrinsics  provide  a  number  of  utility  functions  that  you  can  use  to: 

•  Determine  the  number  of  elements  in  an  array. 

•  Translate  strings  to  widget  instances. 

•  Manage  memory  usage. 

•  Share  graphics  contexts. 

•  Manipulate  selections. 

•  Merge  exposure  events  into  a  region. 
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Translate  widget  coordinates. 
Translate  a  window  to  a  widget 
Handle  errors. 


For  related  discussion,  see  the  following  Xt  routines  and  prototype  procedures: 


XtAddExposureToRegion  ( 1 ) 
XtAppErrorMsg  ( 1 ) 
XtAppError(\) 

XtAppGetErrorDatabaseText  ( 1 ) 
XtAppGetErrorDatabase  ( 1 ) 
XtAppGetSelectionTimeout(l) 
XtAppSetSelectionTimeout  ( 1 ) 
XtAppSetWarningHandler  ( 1 ) 
XtAppSetWarningMsgHandler  ( 1 ) 
XtAppWarningMsg  ( 1 ) 
XtAppWarning(l) 
XtCalloc(l) 


XtDisownSelection  ( 1 ) 

XtFindFile(l) 

XtFree(\) 

XtGetGC(\) 

XtGetSelectionRequest(\ ) 

XtMaltoc(l) 

XtNameToWidget(l) 

XtNewString(l) 

XtNew(l) 

XtNumber(\) 

XtOwnSelectionlncrementcd  ( 1 ) 

XtO\vnSelection(\) 


XtRealloc(\) 

XtReleaseGC(l) 

XtResolvePathname  ( 1 ) 

XtSetWMColormapWindows(l) 

XfTranslateCoords  ( 1 ) 

XtWindowToWidget(l) 

XtAppSetErrorHandler  (2) 

XtAppSetErrorMsgHandler  (2) 

XtErrorHandler(2) 

XtErrorMsgHandlerW 

XtFilePredicate(2) 


1.12  Non-widget  Objects 

Although  widget  writers  are  free  to  treat  Core  as  the  base  class  of  the  widget  hierarchy,  there 
are  actually  three  classes  above  it  These  classes  are  Object,  RectObj  (Rectangle  Object)  and 
"unnamed."  They  are  genetically  referred  to  as  objects.  By  convention,  the  term  widget 
refers  only  to  objects  that  are  a  subclass  of  Core,  and  the  term  non-widget  refers  to  objects 
that  are  not  a  subclass  of  Core. 

The  Object  class  exists  so  that  programmers  can  use  the  classing  and  resource  handling 
mechanisms  for  things  besides  widgets.  Objects  make  many  common  uses  of  subresources 
obsolete. 

Rectangle  objects  are  a  subclass  of  Object  that  represent  rectangular  areas.  They  encapsulate 
the  mechanisms  for  geometry  management  and  are  called  RectObjs  to  avoid  conflict  with  the 
Xlib  Rectangle  data  type. 
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How  to  Use  the  Permuted  Index 

The  permuted  index  takes  the  brief  descriptive  string  from  the  title  of  each  command  page 
and  rotates  (permutes)  the  string  so  that  each  keyword  will  at  one  point  start  the  second,  or 
center,  column  of  the  line.  The  beginning  and  end  of  the  original  string  are  indicated  by  a 
slash  when  they  are  in  other  than  their  original  position;  if  the  string  is  too  long,  it  is  trun 
cated. 

To  find  the  command  you  want,  simply  scan  down  the  middle  of  the  page,  looking  for  a  key 
word  of  interest  on  the  right  side  of  the  blank  gutter.  Once  you  find  the  keyword  you  want, 
you  can  read  (with  contortions)  the  brief  description  of  the  command  that  makes  up  the  entry. 
If  things  still  look  promising,  you  can  look  all  the  way  over  to  the  right  for  the  name  of  the 
relevant  command  page. 

The  Permuted  Index 

XtParseAcceleratorTable:  compile  an  accelerator  table  into  its  internal/ XtParseAcceleratorTaWe(1 ) 

Core  method  to  display  current  accelerators  display_accelerator: display_accelerator(4) 

descendants  onto  a/  /install  all  accelerators  from  a  widget  and  its XtlnstallAIIAccelerators(1 ) 

/install  a  widget's  accelerators  on  another  widget XtlnstallAccelerators(1 ) 

accepting  or  rejecting  the/  acceptjocus:  Core  method  for accept_focus(4) 

XtCallAcceptFocus:  call  a  widget's  acceptjocus  procedure XtCallAcceptFocus(1 ) 

acceptjocus:  Core  method  for  accepting  or  rejecting  the  keyboard/ acceptjocus (4) 

XtMenuPopdown:  built-in  action  for  popping  down  a  widget XtMenuPopdown(1 ) 

XtMenuPopup:  built-in  action  for  popping  up  a  widget XtMenuPopup(1 ) 

XtActionHookProc:  prototype  action  hook  procedure XtActionHookProc(2) 

XtRemoveActionHook:  unregister  an  action  hook  procedure XtRemoveActionHook(1 ) 

XtAppAddActionHook:  add  an  action  hook XtAppAddActionHook(1 ) 

events  XtCallActionProc:  invoke  an  action  procedure  without  generating XtCallActionProc(l) 

XtActionProc:  prototype  action  procedure XtActionProc(2) 

the/  XtAppAddActions:  declare  an  action  table  and  register  it  with XtAppAddActions(1 ) 

Manager  XtAddActions:  register  an  action  table  with  the  Translation XtAddActions(1 ) 

Command:  command  button  activated  by  pointer  click Command(5) 

XtUngrabKeyboard:  cancel  an  active  keyboard  grab Xtl)ngrabKeyboard(l) 

XtUngrabPointer:  cancel  an  active  pointer  grab XtUngrabPointer(l) 

XtGrabKey board:  actively  grab  the  keyboard XtGrabKeyboard(1 ) 

XtGrabPointer:  actively  grab  the  pointer XtGrabPointer(1 ) 
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widget's  callback/  XtAddCallback: 

context  /open,  initialize,  and 

to  a  given/  XtAddCallbacks: 

of  managed  children  XtManageChild: 

XtAppAddActionHook: 

/initialize  a  display  and 

of  managed/  XtManageChildren: 

specifying  the  callback  list  by 

XtVaCreateArgsList:  dynamically 

elements  to  zero  XtCalloc: 

of  a  data  type  XtNew: 

XtMalloc: 

XtFree:  free  an 

XtRealloc:  change  the  size  of  an 

/the  display  pointer  for  the  nearest 

/the  screen  pointer  for  the  nearest 

/return  the  window  for  the  nearest 

ApplicationShell:  main  shell  for  an 

displays  /destroy  an 

a  Display  /retrieve  the 

widget  /get  the 

/the  X  Toolkit  internals,  create  an 

a  type  converter  in  a  single 

a  display  and  remove  it  from  an 

/create  an 

a  display  and  add  it  to  an 

initialize,  and  add  a  display  to  an 

/register  a  type  converter  for  all 

passed  to/  /return  the 

window  managers  WMShell: 

a  display,  and  create  the  initial 

additional  top-level  shell  for  an 

/retrieve  resources  for  the  overall 

XtGetApplicationResources:  set 

new  file  as  an  input  source  for  an 

register  a  work  procedure  for  an 

a  new  resource  converter  for  an 

file  as  an  input  source  for  a  given 

a  work  procedure  for  a  given 

process  input  from  a  given 

spring-loaded  pop-up  from  within  an 

/examine  the  head  of  an 

/whether  any  events  are  in  an 

/examine  the  head  of  an 

/if  there  are  any  events  in  an 

/return  next  event  from  an 

application 

/a  widget  is  a  subclass  of  the 

top-level  widget  that  handles 

XtMergeArgLJsts:  merge  two 

/copy  resource  settings  from  an 

XtSetValues:  copy  resources  from  an 

/prototype  procedure  for 


add  a  callback  procedure  to  a XtAddCallback(l) 

add  a  display  to  an  application XtOpenDisplay ( 1 ) 

add  a  list  of  callback  procedures XtAddCallbacks(1 ) 

add  a  widget  to  its  parent's  list XtManageChild(1 ) 

add  an  action  hook XtAppAddActionHook(l) 

add  it  to  an  application  context XtDisplay  Initialize^ ) 

add  widgets  to  their  parent's  list XtManageChildren(l) 

address  /in  a  callback  list XtCallCallbackLJst(l) 

allocate  a  varargs  list  for  use/ XtVaCreateArgsLJst(l) 

allocate  an  array  and  initialize XtCalloc(1 ) 

allocate  storage  for  one  instance XtNew(1 ) 

allocate  storage XtMalloc(1) 

allocated  block  of  storage XtFree(1 ) 

allocated  block  of  storage XtRealloc(l) 

ancestor  of  object  that  is  of  class/ XtDisplayOfObject(l) 

ancestor  of  object  that  is  of  class/ XtScreenOfObject(l) 

ancestor  of  object  that  is  of  class/ XtWindowOfObject(l) 

application ApplicationShell(3) 

application  context  and  close  its XtDestroyApplicationContext(l) 

application  context  associated  with XtDisplayToApplicationContext(1 ) 

application  context  for  a  given XtWidgetToApplicationContext(l) 

application  context,  open  a/ XtApplnitialize(l) 

application  context  /register XtAppSetTypeConverter(l) 

application  context  /close XtCloseDisplay(l) 

application  context XtCreateApplicationContext(l) 

application  context  /initialize XtDisplaylnitialize(l) 

application  context  /open XtOpenDisplay(1 ) 

application  contexts  in  a  process XtSetTypeConverter(l) 

application  name  and  class  as XtGetApplicationNameAndClass(l) 

application  resources  linking WMShell(3) 

application  shell  instance  /open XtApplnitialize(l) 

application  TopLevelShell: TopLevelShell(3)    , ' 

application  using  varargs  argument/ XtVaGetApplicationResources(l) 

application  variables  from  resource/ XtGetApplicationResources(1 ) 

application  XtAddlnput:  register  a XtAddlnput(l) 

application  XtAddWorkProc: XtAddWorkProc(l) 

application  /register XtAppAddConverter(1 ) 

application  /register  a  new XtAppAddlnput(l) 

application  /register XtAppAddWorkProc(1 ) 

application  XtAppMainLoop: XtAppMainLoop(1) 

application  /map  a XtPopupSpringLoaded(l) 

application's  input  queue XtAppPeekEvent(1 ) 

application's  input  queue XtAppPending(l) 

application's  input  queue XtPeekEvent(l) 

application's  input  queue XtPending(l) 

application's  X  event  queue XtAppNextEvent(l) 

ApplicationShell:  main  shell  for  an ApplicationShell(3) 

ApplicationShell  widget  class XtlsApplicationShell(l) 

application/window  manager/  Shell: Shell(3) 

ArgList  structures XtMergeArgLists(1 ) 

ArgList  to  a  subpart  resource  list XtSetSubvalues(l) 

ArgList  to  a  widget XtSetValues(l) 

argument  conversion XtConvertArgProc(2) 
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XtSetArg:  modify  an  argument  list  dynamically XtSetArg(1 ) 

from  subpart  data  structure  to  the  argument  list  XtGetSubvalues:  copy XtGetSubvalues(1 ) 

copy  resources  from  a  widget  to  the  argument  list  XtGetValues: XtGetValues(1 ) 

of  a  widget  tree,  using  varargs  argument  style  /that  is  the  root XtVaAppCreateShell(l) 

X  Toolkit  internals,  using  varargs   argument  style  /initialize  the XtVaApplnitialize(l) 

a  single  procedure,  using  varargs   argument  style  /a  child  widget  in XtVaCreateManagedWidget(1 ) 

a  pop-up  shell,  using  varargs  argument  style  /create XtVaCreatePopupShell(1 ) 

instance  of  a  widget  using  varargs  argument  style  /create  an XtVaCreateWidget(1 ) 

overall  application  using  varargs   argument  style  /resources  for  the XtVaGetApplicationResources(1 ) 

for  widget  subparts,  using  varargs  argument  style  /fetch  resources XtVaGetSubresources(1 ) 

a  widget  instance,  using  varargs  argument  style  /associated  with XtVaGetSubvalues(1 ) 

a  widget  instance,  using  varargs  argument  style  /associated  with XtVaGetValues(l) 

a  widget  instance,  using  varargs  argument  style  /associated  with XtVaSetSubvalues(1 ) 

a  widget  instance,  using  varargs  argument  style  /associated  with XtVaSetValues(1 ) 

zero  XtCalloc:  allocate  an  array  and  initialize  elements  to XtCalloc(1) 

method  to  insert  a  child  into  the  array  of  children  /Composite insert_child(4) 

number  of  elements  in  a  fixed-size  array  XtNumber:  determine  the XtNumber(1) 

widgets  Grip:  attachment  point  for  dragging  other Grip(5) 

realize:  Core  method  to  set  window  attributes  and  create  window realize(4) 

prototype  procedure  for  performing   background  processing  XtWorkProc: XtWorkProc(2) 

management  RectObj:   base  class  encapsulating  geometry  RectObj(3) 

management  and  callbacks  Object:   base  class  encapsulating  resource Object(3) 

Sme:   base  class  for  menu  entries Sme(5) 

SmeBSB:   basic  menu  entry SmeBSB(5) 

window  according  to  the  event   bindings  in  the  widget's/  /widget's XtRegisterGrabAction(l) 

XtFree:  free  an  allocated   block  of  storage XtFree(1 ) 

change  the  size  of  an  allocated   block  of  storage  XtRealloc: XtRealloc(1 ) 

XtStringConversionWaming:  emit  boilerplate  string  conversion  error/ XtStringConversionWarning(1 ) 

Toggle:  button  which  maintains   boolean  state Toggle(5) 

Box:  geometry-managing  box  widget Box (5) 

Box:  geometry-managing   box  widget Box(5) 

Dialog:  dialog   box  widget Dialog(5) 

widget  XtMenuPopdown:   built-in  action  for  popping  down  a XtMenuPopdown(1 ) 

widget  XtMenuPopup:  built-in  action  for  popping  up  a XtMenuPopup(1 ) 

Command:  command   button  activated  by  pointer  click Command(5) 

XtRegisterGrabAction:  register  button  and  key  grabs  for  a  widget's/ XtRegisterGrabAction(1 ) 

XtUngrabButton:  cancel  a  passive  button  grab XtUngrabButton(1 ) 

state  Toggle:   button  which  maintains  boolean Toggle(5) 

MenuButton:   button  which  pops  up  a  menu MenuButton(S) 

passively  grab  a  single  pointer  button  XtGrabButton: XtGrabButton(1 ) 

structure/  XtOffset:  determine  the  byte  offset  of  a  field  within  a XtOffset(1) 

XtOffsetOf :  determine  the  byte  offset  of  a  field  within  a/ XtOffsetOf(1 ) 

perform  resource  conversion  and  cache  result  XtDirectConvert: XtDirectConvert(l) 

prototype  procedure  to  destroy   cached  resource  data  XtDestructor: XtDestructor(2) 

/callback  function  to  release  a  cached  resource  value XtCallbackReleaseCacheRef(l) 

/decrement  the  reference  counts  for  cached  resources  obtained  from/ XtAppReleaseCacheRefs(1 ) 

function  to  release  a  list  of  cached  values  /callback XtCallbackReleaseCacheRefLJst(1 ) 

the/  XtConvertAndStore:  look  up  and  call  a  resource  converter,  copying XtConvertAndStore(1 ) 

procedure  XtCallAcceptFocus:  call  a  widget's  acceptjocus XtCallAcceptFocus(1 ) 

handler  XtAppErrorMsg:  call  the  high-level  fatal  error XtAppErrorMsg(1 ) 

handler  XtErrorMsg:  call  the  high-level  fatal  error XtErrorMsg(1 ) 

procedure  XtAppError:  call  the  installed  fatal  error XtAppError(l) 

warning  handler  XtAppWamingMsg:  call  the  installed  high-level XtAppWamingMsg(1 ) 
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warning  handler  XtWamingMsg:  call  the  installed  high-level XtWamingMsg(l) 

warning  handler  XtWaming:  call  the  installed  low-level XtWarning(l) 

procedure  XtAppWarning:  call  the  installed  nonfatal  error XtAppWaming(l) 

handler  XtError:  call  the  low-level  fatal  error XtError(1) 

widget  XtCallbackExclusive:  callback  function  to  pop  up  a XtCallbackExclusive(l) 

widget  XtCallbackNone:  callback  function  to  pop  up  a XtCallbackNone(l) 

widget.  XtCallbackNonexclusive:  callback  function  to  pop  up  a XtCallbackNonexclusive(l) 

cached/  XtCallbackReleaseCacheRef :  callback  function  to  release  a XtCallbackReleaseCacheRef(1 ) 

of/  XtCallbackReleaseCacheReflJst:  callback  function  to  release  a  list XtCallbackReleaseCacheRefList(1 ) 

/in  a  callback  list,  specifying  the  callback  list  by  address XtCallCallbackList(1 ) 

/execute  the  procedures  in  a  callback  list,  specifying  the/ XtCallCallbackLJst(1 ) 

procedures  to  a  given  widget's  callback  list  /a  list  of  callback XtAddCallbacks(1 ) 

the  procedures  in  a  widget's  callback  list  /execute XtCallCallbacks(1 ) 

determine  the  status  of  a  widget's  callback  list  XtHasCallbacks: XtHasCallbacks(l) 

/delete  all  procedures  from  a  callback  list XtRemoveAIICallbacks(l) 

delete  a  procedure  from  a  callback  list  XtRemoveCallback: XtRemoveCallback(l) 

delete  a  list  of  procedures  from  a  callback  list  XtRemoveCallbacks: XtRemoveCallbacks(1 ) 

XtTimerCallbackProc:  prototype  callback  procedure  invoked  when/ XtTimerCallbackProc(2) 

callback/  XtAddCallback:  add  a  callback  procedure  to  a  widget's XtAddCallback(l) 

XtCallbackProc:  prototype  callback  procedure XtCallbackProc(2) 

XtAddCallbacks:  add  a  list  of  callback  procedures  to  a  given/ XtAddCallbacks(l) 

a  callback  procedure  to  a  widget's  callback  resource  /add XtAddCallback(1 ) 

/pop  down  a  widget  from  a  callback  routine XtCallbackPopdown(1 ) 

resource  management  and  callbacks  /base  class  encapsulating Object(3) 

completes  /prototype  procedure  called  after  a  data  transfer XtSelectionDoneProc(2) 

claims  the/  /prototype  procedure  called  by  Xt  when  another  client XtLoseSelectionProc(2) 

/register  a  procedure  to  be  called  on  fatal  error  conditions XtAppSetErrorHandler(1 ) 

/register  a  procedure  to  be  called  on  fatal  error  conditions XtAppSetErrorMsgHandler(1 ) 

/register  a  procedure  to  be  called  on  fatal  error  conditions XtSetErrorHandler(l) 

/register  a  procedure  to  be  called  on  nonfatal  error  conditions XtAppSetWamingHandler(l) 

/register  a  procedure  to  be  called  on  nonfatal  error/ XtAppSetWamingMsgHandler(1 ) 

/register  a  procedure  to  be  called  on  nonfatal  error  conditions XtSetErrorMsgHandler(1 ) 

/register  a  procedure  to  be  called  on  nonfatal  error  conditions XtSetWamingHandler(1 ) 

la  high-level  procedure  to  be  called  on  nonfatal  error  conditions XtSetWamingMsgHandler(l) 

XtCaseProc:  prototype  procedure  called  to  convert  the  case  of/ XtCaseProc(2) 

socket  input  /prototype  procedure  called  to  handle  file,  pipe,  or XtlnputCallbackProc(2) 

delete_child:  Composite  method  called  when  a  child  is  destroyed delete_child(4) 

geometry_manager:  Composite  method  called  when  a  child  requests  a  new/ geometry_manager(4) 

destroy:  Core  method  called  when  a  widget  is  destroyed destroy(4) 

query jjeometry:  Core  method  called  when  a  widget  is  destroyed query_geometry(4) 

resize:  Core  method  called  when  a  widget  is  resized resize(4) 

data  arrives  /prototype  procedure  called  when  requested  selection XtSelectionCallbackProc(2) 

symbol  in  multiple  varargs  calls  /use  with  the  XtVaNestedLJst XtVaCreateArgsLJst(l) 

XtUngrabButton:  cancel  a  passive  button  grab XtUngrabButton(l) 

XtUngrabKey :  cancel  a  passive  key  grab XtUngrabKey  (1 ) 

XtUngrabKey board :  cancel  an  active  keyboard  grab XtUngrabKey board(1 ) 

XtUngrabPointer:  cancel  an  active  pointer  grab XtUngrabPointer(1 ) 

transfer  /prototype  procedure  to  cancel  incremental  selection XtCancelConvertSelectionProc(2) 

XtRegisterCaseConverter:  register  a  case  converter XtRegisterCaseConverter(1 ) 

procedure  called  to  convert  the  case  of  keysyms  /prototype XtCaseProc(2) 

/request  parent  to  change  child's  geometry XtMakeGeometryRequest(l) 

/request  parent  to  change  child's  size XtMakeResizeRequest(l) 

/Composite  method  to  respond  to  a  change  in  a  list  of  managed  widgets  change_managed(4) 
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block  of  storage  XtRealloc:  change  the  size  of  an  allocated XtRealloc(1 ) 

XtSetMappedWhenManaged:  change  the  value  of  a  widget's/ XtSetMappedWhenManaged(1 ) 

respond  to  a  change  in  a  list  of/  changejnanaged:  Composite  method  to change_managed(4) 

for  processing  constraint  resource  changes  /Constraint  method Constraint  set_yalues(4) 

Core  method  for  processing  resource  changes  set_yalues: set_values(4) 

to  display  a  real-time  graphic  chart  StripChart:  widget StripChart(S) 

of  a  widget  XtlsSensitive:  check  the  current  sensitivity  state XtlsSensitive(1 ) 

/Composite  method  to  insert  a  child  into  the  array  of  children insert_child(4) 

method  for  cleaning  up  after  a  child  is  destroyed  /Constraint Constraint  destroy(4) 

Composite  method  called  when  a  child  is  destroyed  delete_child: delete_child(4) 

XtResizeWidget:  resize  a  child  or  sibling  widget XtResizeWidget(l) 

/Composite  method  called  when  a  child  requests  a  new  geometry geometry_manager(4) 

using  varargs/  /create  and  manage  a  child  widget  in  a  single  procedure,  XtVaCreateManaged Widget(1 ) 

/create  and  manage  a  child  widget XtCreateManagedWidget(l) 

input  to  a  normal  descendant  of  a  child  widget  /redirect  keyboard XtSetKey  boardFocus(1 ) 

XtQuery Geometry:  query  a  child  widget's  preferred  geometry XtQueryGeometry(l) 

to  determine  position  for  new  child  /Composite  function XtOrderProc(2) 

widget  implementing  constraints  on  children  Form:  geometry-managing Form(5) 

managed  list  /remove  a  list  of  children  from  a  parent  widget's XtUnmanageChildren(1 ) 

to  insert  a  child  into  the  array  of  children  /Composite  method insert_child(4) 

to  its  parent's  list  of  managed  children  /add  a  widget XtManageChild(1 ) 

to  their  parent's  list  of  managed  children  /add  widgets XtManageChildren(1 ) 

/request  parent  to  change  child's  geometry XtMakeGeometryRequest(1 ) 

request  parent  to  change  child's  size  XtMakeResizeRequest: XtMakeResizeRequest(1 ) 

called  by  Xt  when  another  client  claims  the  selection  /procedure XtLoseSelectionProc(2) 

/return  the  application  name  and  class  as  passed  to/ XtGetApplicationNameAndClass(1 ) 

for  dynamically  initializing  the  class  /Core  method class_initialize(4) 

management  RectObj:  base  class  encapsulating  geometry RectObj(3) 

management  and/  Object:  base  class  encapsulating  resource Object(3) 

Sme:  base  class  for  menu  entries Sme(5) 

/Core  method  to  initialize  class  part  structure  fields class_part_initialize(4) 

ancestor  of  object  that  is  of  class  Widget  /for  the  nearest XtDisplayOfObject(1 ) 

ancestor  of  object  that  is  of  class  Widget  /for  the  nearest XtScreenOfObject(1 ) 

ancestor  of  object  that  is  of  class  Widget  /for  the  nearest XtWindowOfObject(l) 

/initialize  a  widget  class  without  creating  any  widgets XtlnitializeWidgetClass(1 ) 

in  DEBUG  mode,  verify  an  object's  class  XtCheckSubclass: XtCheckSubclass(l) 

XtClass:  obtain  a  widget's  class XtClass(1) 

structure  for  a  particular  widget  class  /the  constraint  resource  list XtGetConstraintResourceList(1 ) 

of  the  ApplicationShell  widget  class  /a  widget  is  a  subclass XtlsApplicationShell(1 ) 

a  subclass  of  the  Composite  widget  class  /test  whether  a  widget  is XtlsComposite(1 ) 

a  subclass  of  the  Constraint  widget  class  Aest  whether  a  widget  is XtlsConstraint(1 ) 

is  a  subclass  of  the  Object  widget  class  /test  whether  a  widget Xt  Is0bject(1 ) 

of  the  OvemdeShell  widget  class  /a  widget  is  a  subclass XtlsOverrideShell(1 ) 

is  a  subclass  of  the  RectObj  widget  class  /test  whether  a  widget XtlsRectObj(1 ) 

is  a  subclass  of  the  Shell  widget  class  Aest  whether  a  widget Xt lsShell(1 ) 

whether  a  widget  is  a  subclass  of  a  class  XtlsSubclass:  determine XtlsSubclass(1 ) 

of  the  TopLevelShell  widget  class  la  widget  is  a  subclass XtlsTopLevelShell(1 ) 

of  the  TransientShell  widget  class  /a  widget  is  a  subclass XtlsTransientShell(1 ) 

subclass  of  the  VendorShell  widget  class  Aest  whether  a  widget  is  a XtlsVendorShell(l) 

is  a  subclass  of  the  Core  widget  class  Aest  whether  a  widget Xt  Is  Widget(1 ) 

is  a  subclass  of  the  WMShell  widget  class  Aest  whether  a  widget Xt  Is  WMShell(1 ) 

dynamically  initializing  the  class  classjnitialize:  Core  method  for class_initialize(4) 

to  initialize  class  part  structure/  class_part_initialize:  Core  method class_part_initialize(4) 
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destroyed  /Constraint  method  for  cleaning  up  after  a  child  is Constraint  destroy(4) 

command  button  activated  by  pointer  click  Command: Command(5) 

/procedure  called  by  Xt  when  another  client  claims  the  selection XtLoseSelectionProc(2) 

an  application/  XtCloseDisplay:  close  a  display  and  remove  it  from XtCloseDisplay(l) 

/destroy  an  application  context  and  close  its  displays XtDestroyApplicationContext(1 ) 

to  inform  window  manager  of  custom  colormaps  /property XtSetWMColormapWindows(l) 

click  Command:  command  button  activated  by  pointer Command(5) 

by  pointer  click  Command:  command  button  activated Command(5) 

read-only/  XtDestroyGC:  Release  2  compatible  function  to  free XtDestroyGC(l) 

its/  XtParseTranslationTable:  compile  a  translation  table  into XtParseTranslationTable(1 ) 

its/  XtParseAcceleratorTaWe:  compile  an  accelerator  table  into XtParseAcceleratorTable(1 ) 

XtGetSelectionValue:  obtain  the  complete  selection  data XtGetSelectionValue(l) 

called  after  a  data  transfer  completes  /prototype  procedure XtSelectionDoneProc(2) 

/prototype  procedure  to  indicate  completion  of  incremental  transfer XtSelectionDonelncrProc(2) 

geometry  management  Composite:  defines  methods  for Composite(3) 

position  for  new/  XtOrderProc:  Composite  function  to  determine XtOrderProc(2) 

child  is  destroyed  delete_child:  Composite  method  called  when  a delete_child(4) 

child  requests  a/  geometryjnanager:  Composite  method  called  when  a geometry_manager(4) 

into  the  array  of/  insert_child:  Composite  method  to  insert  a  child insert_child(4) 

change  in  a  list/  changejnanaged:  Composite  method  to  respond  to  a change_managed(4) 

a  widget  is  a  subclass  of  the  Composite  widget  class  /whether XtlsComposite(1 ) 

/Core  method  to  negotiate  compromise  geometries  set_values_almost(4) 

to  be  called  on  fatal  error  conditions  /register  a  procedure XtAppSetErrorHandler(1 ) 

to  be  called  on  fatal  error  conditions  /register  a  procedure XtAppSetErrorMsgHandler(1 ) 

to  be  called  on  nonfatal  error  conditions  /register  a  procedure XtAppSetWamingHandler(1 ) 

to  be  called  on  nonfatal  error  conditions,  /register  a  procedure XtAppSetWamingMsgHandler(1 ) 

to  be  called  on  fatal  error  conditions  /register  a  procedure XtSetErrorHandler(1 ) 

to  be  called  on  nonfatal  error  conditions  /register  a  procedure XtSetErrorMsgHandler(1 ) 

to  be  called  on  nonfatal  error  conditions  /register  a  procedure XtSetWamingHandler(l) 

to  be  called  on  nonfatal  error  conditions  /a  high-level  procedure XtSetWamingMsgHandler(l) 

after  a  child/  Constraint  destroy:  Constraint  method  for  cleaning  up Constraint  destroy(4) 

constraint/  Constraint  set_values:  Constraint  method  for  processing Constraint  set_values(4) 

Constraint  initialize:  Constraint  method  to  initialize Constraint  initialize^) 

structures  for  a  widget's  parent  Constraint:  provides  data Constraint(3) 

/Constraint  method  for  processing  constraint  resource  changes Constraint  set_values(4) 

for  a  particular  widget/  /get  the  constraint  resource  list  structure XtGetConstraintResourceLJst(1 ) 

a  widget  is  a  subclass  of  the  Constraint  widget  class  /whether XtlsConstraint(l) 

method  for  cleaning  up  after  a/  Constraint  destroy:  Constraint Constraint  destroy(4) 

method  to  initialize  Constraint  initialize:  Constraint Constraint  initialize^) 

method  for  processing  constraint/  Constraint  set_values:  Constraint Constraint  set_values(4) 

/widget  implementing  constraints  on  children Form(5) 

SimpleMenu:  menu  container  widget SimpleMenu(5) 

handled  by  XtDispatchEvent  that  contains  a  timestamp  /recent  event XtLastTimestampProcessed(1 ) 

/destroy  an  application  context  and  close  its  displays XtDestroyApplicationContext(1 ) 

/retrieve  the  application  context  associated  with  a  Display XtDisplayToApplicationContext(1 ) 

/get  the  application  context  for  a  given  widget XtWidgetToApplicationContext(1 ) 

/internals,  create  an  application  context,  open  a  display,  and  create/ XtApplnitialize(1 ) 

converter  in  a  single  application  context  /register  a  type XtAppSetTypeConverter(l) 

and  remove  it  from  an  application  context  /close  a  display XtCloseDisplay(l) 

/create  an  application  context XtCreateApplicationContext(l) 

and  add  it  to  an  application  context  /initialize  a  display XtDisplay  Initialize^ ) 

and  add  a  display  to  an  application  context  /open,  initialize XtOpenDisplay(1 ) 

type  converter  for  all  application  contexts  in  a  process,  /register  a XtSetTypeConverter(1 ) 
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XtMainLoop:  continuously  process  events XtMainLoop(1) 

in  another/  Scrollbar:  widget  to  control  scrolling  of  viewing  area Scrollbar(5) 

XtDirectConvert:  perform  resource  conversion  and  cache  result XtDirectConvert(l) 

/emit  boilerplate  string  conversion  error  message XtStringConversionWarning(1 ) 

/issue  a  warning  message  during  conversion  of  string  resource/ XtDisplayStringConversionWarning(1 ) 

prototype  procedure  for  argument  conversion.  XtConvertArgProc: XtConvertArgProc(2) 

explicitly  invoke  resource  conversions  XtCallConverter: XtCallConverter(l) 

/prototype  procedure  to  convert  incremental  selection  data XtConvertSelectionlncrProc(2) 

XtConvert:  convert  resource  type XtConvert(l) 

/prototype  procedure  to  convert  selection  data XtConvertSelectionProc(2) 

/prototype  procedure  called  to  convert  the  case  of  keysyms XtCaseProc(2) 

value  /look  up  and  call  a  resource  converter,  copying  the  resulting XtConvertAndStore(1 ) 

XtSetTypeConverter:  register  a  type  converter  for  all  application/ XtSetTypeConverter(1 ) 

/register  a  new  resource  converter  for  an  application XtAppAddConverter(1 ) 

context  /register  a  type  converter  in  a  single  application XtAppSetTypeConverter(1 ) 

prototype  of  a  resource  converter  procedure  XtConverter: XtConverter(2) 

/procedure  passed  as  a  resource  converter  when  XtRCallProc  is/ XtResourceDefaultProc(2) 

register  a  new  resource  converter  XtAddConverter: XtAddConverter(l) 

register  a  case  converter  XtRegisterCaseConverter: XtRegisterCaseConverter(1 ) 

procedure  for  a  new-style  resource  converter  /prototype XtTypeConverter(2) 

/event  that  triggered  the  convert_selection  procedure XtGetSelectionRequest(1 ) 

XtTranslateCoords:  translate  an  x-y  coordinate  pair  from  widget/ XtTranslateCoords(1 ) 

/an  x-y  coordinate  pair  from  widget  coordinates  to  root  coordinates XtTranslateCoords(1 ) 

from  widget  coordinates  to  root  coordinates  /an  x-y  coordinate  pair XtTranslateCoords(l) 

XtNewString:  copy  an  instance  of  a  string XtNewString(1 ) 

the  argument  list  XtGetSubvalues:  copy  from  subpart  data  structure  to XtGetSubvalues(1 ) 

ArgList  to  a/  XtSetSubvalues:  copy  resource  settings  from  an XtSetSubvalues(l) 

argument  list  XtGetValues:  copy  resources  from  a  widget  to  the XtGetValues(l) 

widget  XtSetValues:  copy  resources  from  an  ArgList  to  a XtSetValues(l) 

up  and  call  a  resource  converter,  copying  the  resulting  value  /look XtConvertAndStore(1 ) 

resize  a  widget  according  to  its  core  dimensions  XtResizeWindow: XtResizeWindow(1 ) 

Core:  fundamental  widget Core(3) 

destroyed  destroy:  Core  method  called  when  a  widget  is destroy(4) 

destroyed  query jjeometry:  Core  method  called  when  a  widget  is queryjgeometry(4) 

resized  resize:  Core  method  called  when  a  widget  is resize(4) 

rejecting  the/  acceptjocus:  Core  method  for  accepting  or accept_focus(4) 

expose:  Core  method  for  drawing  graphics expose(4) 

initializing  the/  classjnitialize:  Core  method  for  dynamically class_initialize(4) 

resource  values  get_yalues_hook:  Core  method  for  getting  subpart get_values_hook(4) 

instance  variables  initialize:  Core  method  for  initializing  initialize^) 

subpart  data  initialize_hook:  Core  method  for  initializing initialize_hook(4) 

changes  set_values:  Core  method  for  processing  resource set_values(4) 

resources  set_values_hook:  Core  method  for  processing  subpart set_values_hcok(4) 

accelerators  display_accelerator:  Core  method  to  display  current display_accelerator(4) 

part/  classjartjnitialize:  Core  method  to  initialize  class class _part_initialize(4) 

geometries  set_values_almost:  Core  method  to  negotiate  compromise set_values_almost(4) 

attributes  and  create/  realize:  Core  method  to  set  window realize(4) 

a  widget  is  a  subclass  of  the  Core  widget  class  /test  whether XtlsWidget(1 ) 

/explicitly  decrement  the  reference  counts  for  cached  resources/ XtAppReleaseCacheRefs(1 ) 

Template:  widget  to  create  a  custom  widget Template(5) 

varargs/  XtVaCreatePopupShell:  create  a  pop-up  shell,  using XtVaCreatePopupShell(1 ) 

XtCreatePopupShell:  create  a  pop-up  shell XtCreatePopupShell(1 ) 

XtAddTimeOut:  create  a  timeout  value XtAddTimeOut(1 ) 


Permuted  Index 


31 


the  root  of  a/  XtVaAppCreateShell:  create  a  top-level  widget  that  is XtVaAppCreateShell(1 ) 

XtAppCreateShell:  create  additional  top-level  widget XtAppCreateShell(1 ) 

widget  XtCreateApplicationShell:  create  an  additional  top-level XtCreateApplicationShell(l) 

/initialize  the  X  Toolkit  internals,  create  an  application  context,  open/ XtApplnitialize(1 ) 

XtCreateApplicationContext:  create  an  application  context XtCreateApplicationContext(l) 

using  varargs/  XtVaCreateWidget:  create  an  instance  of  a  widget XtVaCreateWidget(l) 

XtCreateWidget:  create  an  instance  of  a  widget XtCreateWidget(1 ) 

a  single/  XtVaCreateManaged Widget:  create  and  manage  a  child  widget  in XtVaCreateManagedWidget(1 ) 

XtCreateManaged Widget :  create  and  manage  a  child  widget XtCreateManaged Widget(1 ) 

shell/  /context,  open  a  display,  and  create  the  initial  application XtApplnitialize(l) 

XtCreateWindow:  create  widget's  working  window XtCreateWindow(1 ) 

method  to  set  window  attributes  and  create  window  realize:  Core realize(4) 

/initialize  a  widget  class  without  creating  any  widgets Xtlnitia!izeWidgetClass(1 ) 

/Core  method  to  display  current  accelerators display_accelerator(4) 

XtAppGetSelectionTimeout:  get  the  current  selection  timeout  value XtAppGetSelectionTimeout(l) 

XtGetSelectionTimeout:  get  the  current  selection  timeout  value XtGetSelectionTimeout(1 ) 

widget  XtlsSensitive:  check  the  current  sensitivity  state  of  a XtlsSensitive(l) 

XtVaGetSubvalues:  retrieve  the  current  values  of  nonwidget/ XtVaGetSubvalues(l) 

XtVaSetSubvalues:  set  the  current  values  of  nonwidget/ XtVaSetSubvalues(l) 

XtVaGetValues:  retrieve  the  current  values  of  resources/ XtVaGetValues(1 ) 

XtVaSetValues:  modify  the  current  values  of  resources/ XtVaSetValues(1 ) 

XtTranslateKeycode:  invoke  the  currently  registered/ XtTranslateKeycode(1 ) 

to  inform  window  manager  of  custom  colormaps  /property XtSetWMColormapWindows(1 ) 

Template:  widget  to  create  a  custom  widget Template(5) 

called  when  requested  selection  data  arrives  /prototype  procedure XtSelectionCallbackProc(2) 

/obtain  selection  data  in  multiple  formats XtGetSelectionValues(1 ) 

method  for  initializing  subpart  data  initialize_hook:  Core initialize_hook(4) 

indicate  that  selection  data  is  available  XtOwnSelection: XtOwnSelection(1 ) 

/indicate  that  selection  data  is  no  longer  available XtDisownSelection(l) 

XtGetSubvalues:  copy  from  subpart  data  structure  to  the  argument  list XtGetSubvalues(l) 

parent  Constraint:  provides  data  structures  for  a  widget's Constraint^) 

/prototype  procedure  called  after  a  data  transfer  completes XtSelectionDoneProc'(2) 

storage  for  one  instance  of  a  data  type  XtNew:  allocate XtNew(1) 

to  convert  incremental  selection  data  /prototype  procedure XtConvertSelectionlncrProc(2) 

procedure  to  convert  selection  data  /prototype XtConvertSelectionProc(2) 

to  destroy  cached  resource  data  /prototype  procedure XtDestructor(2) 

obtain  the  complete  selection  data  XtGetSelectionValue: XtGetSelectionValue(1 ) 

XtDatabase:  obtain  the  resource  database  for  a  particular  display XtDatabase(1 ) 

warning  /obtain  the  error  database  text  for  an  error  or  a XtAppGetErrorDatabaseText(1 ) 

warning  /obtain  the  error  database  text  for  an  error  or  a XtGetErrorDatabaseText(1 ) 

obtain  the  error  database  XtAppGetErrorOatabase: XtAppGetErrorOatabase(l) 

application  variables  from  resource  database  /set XtGetApplicationResources(1 ) 

obtain  the  error  database  XtGetErrorOatabase: XtGetErrorDatabase(1 ) 

no  longer  needed  XtReleaseGC:  deallocate  a  shared  GC  when  it  is XtReleaseGC(1 ) 

class  XtCheckSubclass:  in  DEBUG  mode,  verify  an  object's XtCheckSubclass(l) 

register  it  with/  XtAppAdd Actions:  declare  an  action  table  and XtAppAddActions(l) 

XtAppReleaseCacheRefs:  explicitly  decrement  the  reference  counts  for/ XtAppReleaseCacheRefs(1 ) 

translator  XtTranslateKey:  the  default  keycode-to-keysym XtTranslateKey(l) 

/specify  a  default  set  of  resource  values XtAppSetFallbackResources(1 ) 

XtGetResourceList:  retrieve  default  values  for  a  resource  list XtGetResourceList(1 ) 

management  Composite:  defines  methods  for  geometry Composite(3) 

callback  list  XtRemoveCallbacks:  delete  a  list  of  procedures  from  a XtRemoveCallbacks(l) 

list  XtRemoveCallback:  delete  a  procedure  from  a  callback XtRemoveCallback(1 ) 
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callback/  XtRemoveAIICallbacks:  delete  all  procedures  from  a XtRemoveAIICallbacks(1 ) 

called  when  a  child  is  destroyed  delete_child:  Composite  method delete_child(4) 

/redirect  keyboard  input  to  a  normal  descendant  of  a  child  widget XtSetKeyboardFocus(1 ) 

accelerators  from  a  widget  and  its   descendants  onto  a  destination  /all XtlnstallAIIAccelerators(1 ) 

associated  with  a  widget  and  its  descendants  /destroy  the  windows XtUnrealizeWidget(1 ) 

a  widget  and  its  descendants  onto  a  destination  /all  accelerators  from Xtlnstall AIIAccelerators(1 ) 

from  modal  widget  back  to  normal  destination  /redirect  user  input XtRemoveGrab(1) 

XtDestroy Widget:  destroy  a  widget  instance XtDestroyWidget(1 ) 

close/  XtDestroyApplicationContext:  destroy  an  application  context  and XtDestroyApplicationContextp ) 

/prototype  procedure  to  destroy  cached  resource  data XtDestructor(2) 

widget  is  destroyed  destroy:  Core  method  called  when  a destroy(4) 

a  widget  and/  XtUnrealizeWidget:   destroy  the  windows  associated  with XtUnrealizeWidget(1 ) 

for  cleaning  up  after  a  child  is  destroyed  /Constraint  method Constraint  destroy(4) 

method  called  when  a  child  is  destroyed  delete_child:  Composite delete_child(4) 

Core  method  called  when  a  widget  is  destroyed  destroy: destroy(4) 

Core  method  called  when  a  widget  is  destroyed  query jjeometry: query_o,eometry(4) 

in  an  application's/  XtPending:  determine  if  there  are  any  events XtPending(l) 

XtOrderProc:  Composite  function  to  determine  position  for  new  child XtOrderProc(2) 

field  within  a  structure/  XtOffset:  determine  the  byte  offset  of  a XtOffset(1 ) 

field  within  a/  XtOffsetOf:  determine  the  byte  offset  of  a XtOffsetOf(1 ) 

a  fixed-size  array  XtNumber:  determine  the  number  of  elements  in XtNumber(1 ) 

callback  list  XtHasCallbacks:  determine  the  status  of  a  widget's XtHasCallbacks(1 ) 

versions  of  a/  XtConvertCase:  determine  upper-case  and  lower-case XtConvertCase(l) 

realized  XtlsRealized:  determine  whether  a  widget  has  been XtlsRealized(1 ) 

subclass  of  a  class  XtlsSubclass:  determine  whether  a  widget  is  a XtlsSubclass(1 ) 

managed  by  its  parent  XtlsManaged:  determine  whether  a  widget  is  XtlsManaged(1 ) 

an  application's/  XtAppPending:  determine  whether  any  events  are  in XtAppPending(l) 

Dialog:  dialog  box  widget Dialog(5) 

Dialog:  dialog  box  widget Dialog(5) 

a  widget  according  to  its  core  dimensions  XtResizeWindow:  resize XtResizeWindow(1 ) 

event  XtDispatchEvent:  dispatch  registered  handlers  for  an XtDispatchEvent(1 ) 

Label:  widget  to  display  a  non-editable  string Label(5) 

StripChart:  widget  to  display  a  real-time  graphic  chart StripChart(5) 

XtDisplay  Initialize:  initialize  a  display  and  add  it  to  an/ XtDisplaylnitialize(l) 

/an  application  context,  open  a  display,  and  create  the  initial/ XtApplnitialize(1 ) 

XtCloseDisplay:  close  a  display  and  remove  it  from  an/ XtCloseDisplay  (1 ) 

display_accelerator:  Core  method  to  display  current  accelerators display_accelerator(4) 

XtDisplayOfObject:  return  the  display  pointer  for  the  nearest/ XtDisplayOfObject(1 ) 

widget  XtDisplay:  return  the  display  pointer  for  the  specified XtDisplay(1 ) 

/translate  a  window  and  display  pointer  into  a  widget  ID XtWindowToWidget(1 ) 

/open,  initialize,  and  add  a  display  to  an  application  context XtOpenDisplay(1 ) 

resource  database  for  a  particular  display  XtDatabase:  obtain  the XtDatabase(l) 

context  associated  with  a  Display  /retrieve  the  application XtDisplay ToApplicationContext(1 ) 

for  a  particular  Display  /to  XtDisplaylnitialize XtGetApplicationNameAndClass(1 ) 

mapping  table  for  a  particular  display  /to  the  keysym-to-keycode XtGetKeysymTable(1 ) 

initialize  toolkit  and  display  Xtlnitialize: Xtlnitialize(1 ) 

XtMapWidget:  map  a  widget  to  its  display XtMapWidget(1 ) 

XtMoveWidget:  move  a  widget  on  the  display XtMoveWidget(1 ) 

display  current  accelerators  display_accelerator:  Core  method  to display_accelerator(4) 

application  context  and  close  its  displays  /destroy  an XtDestroy ApplicationContext(1 ) 

routine  XtCallbackPopdown:  pop  down  a  widget  from  a  callback XtCallbackPopdown(l) 

built-in  action  for  popping  down  a  widget  XtMenuPopdown: XtMenuPopdown(l) 

Grip:  attachment  point  for  dragging  other  widgets Gn'p(5) 
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expose:  Core  method  for  drawing  graphics expose(4) 

for  use  with/  XtVaCreateArgsLJst:  dynamically  allocate  a  varargs  list XtVaCreateArgsLJst(1 ) 

classjnitialize:  Core  method  for  dynamically  initializing  the  class class_initialize(4) 

XtSetArg:  modify  an  argument  list  dynamically XtSetArg(1) 

set  the  multi-click  time  dynamically  XtSetMultiClickTime: XtSetMultiClickTime(l) 

XtNumber:  determine  the  number  of  elements  in  a  fixed-size  array XtNumber(1) 

allocate  an  array  and  initialize  elements  to  zero  XtCalloc: XtCalloc(1) 

error/  XtStringConversionWarning:  emit  boilerplate  string  conversion XtStringConversionWarning(1 ) 

RectObj:  base  class  encapsulating  geometry  management RectObj(3) 

and  callbacks  Object:  base  class  encapsulating  resource  management Object(3) 

Sme:  base  class  for  menu  entries Sme(5) 

SmeBSB:  basic  menu  entry SmeBSB(5) 

in  the  translation  table  entry  /final  event  specification XtGetActionKeysym(l) 

is  specified  in  a  resource  list  entry  /converter  when  XtRCallProc XtResourceDefaultProc(2) 

/prototype  for  low-level  error  and  warning  handlers XtErrorHandler(2) 

/prototype  for  high-level  error  and  warning  handlers XtErrorMsgHandler(2) 

a  procedure  to  be  called  on  fatal  error  conditions  /register XtAppSetErrorHandler(l) 

a  procedure  to  be  called  on  fatal  error  conditions  /register XtAppSetErrorMsgHandler(l) 

procedure  to  be  called  on  nonfatal  error  conditions  /register  a XtAppSetWamingHandler(1 ) 

procedure  to  be  called  on  nonfatal  error  conditions,  /register  a XtAppSetWamingMsgHandler(1 ) 

a  procedure  to  be  called  on  fatal  error  conditions  /register XtSetErrorHandler(l) 

procedure  to  be  called  on  nonfatal  error  conditions  /register  a XtSetErrorMsgHandler(1 ) 

procedure  to  be  called  on  nonfatal  error  conditions  /register  a XtSetWamingHandler(1 ) 

procedure  to  be  called  on  nonfatal  error  conditions  /a  high-level XtSetWamingMsgHandler(1 ) 

a  warning  /obtain  the  error  database  text  for  an  error  or XtAppGetErrorDatabaseText(1 ) 

XtGetErrorDatabaseText:  obtain  the  error  database  text  for  an  error  or/ XtGetErrorDatabaseText(1 ) 

XtAppGetErrorDatabase:  obtain  the  error  database XtAppGetErrorDatabase(l) 

XtGetErrorDatabase:  obtain  the  error  database XtGetErrorDatabase(1 ) 

call  the  high-level  fatal  error  handler  XtAppErrorMsg: XtAppErrorMsg(l) 

XtError:  call  the  low-level  fatal  error  handler XtError(1 ) 

call  the  high-level  fatal  error  handler  XtErrorMsg: XtErrorMsg(l) 

/emit  boilerplate  string  conversion  error  message XtStringConversionWarning(1 ) 

the  error  database  text  for  an  error  or  a  warning  /obtain XtAppGetErrorDatabaseText(1 ) 

the  error  database  text  for  an  error  or  a  warning  /obtain XtGetErrorDatabaseText(1 ) 

call  the  installed  fatal  error  procedure  XtAppEiror: XtAppError(1 ) 

call  the  installed  nonfatal  error  procedure  XtAppWaming: XtAppWarning(1 ) 

procedure  used  in  filename  evaluation  /prototype XtFilePredicate(2) 

a  widget's  window  according  to  the  event  bindings  in  the  widget's/  /for XtRegisterGrabAction(1 ) 

queue  XtAppNextEvent:  return  next  event  from  an  application's  X  event XtAppNextEvent(1 ) 

XtNextEvent:  return  next  event  from  input  queue XtNextEvent(l) 

/the  timestamp  from  the  most  recent  event  handled  by  XtDispatchEvent/ XtLastTimestampProcessed(1 ) 

receives  events  before/  /register  an  event  handler  procedure  that XtlnsertRawEventHandler(l) 

XtlnsertEventHandler:  register  an  event  handler  procedure  that/ XtlnsertEventHandler(l) 

XtEventHandler:  prototype  event  handler  procedure XtEventHandler(2) 

XtAddRawEventHandler:  register  an  event  handler  without  selecting  for/ XtAddRawEventHandler(l) 

/remove  a  previously  registered  event  handler XtRemoveEventHandler(l) 

/remove  a  raw  event  handler XtRemoveRawEventHandler(l) 

/or  after  all  previously  registered  event  handlers,  without  selecting/ XtlnsertRawEventHandler(1 ) 

or  after  all  previously  registered  event  handlers  /events  before XtlnsertEventHandler(1 ) 

retrieve  a  widget's  event  mask  XtBuildEventMask: XtBuildEventMask(l) 

next  event  from  an  application's  X  event  queue  XtAppNextEvent:  return XtAppNextEvent(l) 

modifiers  that  matched  the  final  event  specification  in  the/  /and XtGetActionKeysym(l) 

/retrieve  the  SetectionRequest  event  that  triggered  the/ XtGetSelectionRequest(1 ) 
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handler  without  selecting  for  the  event  /register  an  event XtAddRawEventHandler(1 ) 

process  one  input  event  XtAppProcessEvent: XtAppProcessEvent(1 ) 

dispatch  registered  handlers  for  an  event  XtDispatchEvent: XtDispatchEvent(1 ) 

XtProcessEvent:  process  one  input  event XtProcessEvent(l) 

XtAppPending:  determine  whether  any  events  are  in  an  application's/ XtAppPending(1 ) 

handler  procedure  that  receives  events  before  or  after  all/  /event XtlnsertRawEventHandler(1 ) 

handler  procedure  that  receives  events  before  or  after  all/  /event XtlnsertEventHandler(1 ) 

queue  /determine  if  there  are  any  events  in  an  application's  input XtPending(1 ) 

/merge  Expose  and  GraphicsExpose  events  into  a  region XtAddExposureToRegion(1 ) 

register  a  procedure  to  handle  events  XtAddEventHandler: XtAddEventHandler(1 ) 

action  procedure  without  generating  events  XtCallActionProc:  invoke  an XtCallActionProc(l) 

handlers,  without  selecting  for  the  events  /previously  registered  event XtlnsertRawEventHandler(1 ) 

XtMainLoop:  continuously  process  events XtMaintoop(1) 

callback  list,/  XtCallCallbackList:  execute  the  procedures  in  a XtCallCallbackList(1 ) 

widget's  callback/  XtCallCallbacks:  execute  the  procedures  in  a XtCallCallbacks(l) 

new  translations  with  widget's  existing  ones  /merge XtAugmentTranslations(1 ) 

translations,  overwriting  widget's  existing  ones  /merge  new XtOverrideTranslations(1 ) 

XtUninstallTranslations:  remove  existing  translations XtUninstallTranslations(1 ) 

procedure  invoked  when  timeouts  expire  /prototype  callback XtTimerCallbackProc(2) 

counts  for/  XtAppReleaseCacheRefs:  explicitly  decrement  the  reference XtAppReleaseCacheRefs(1 ) 

conversions  XtCallConverter:  explicitly  invoke  resource XtCallConverter(l) 

XtUnmapWidget:  unmap  a  widget  explicitly XtUnmapWidget(1 ) 

into/  XtAddExposureToRegion:  merge  Expose  and  GraphicsExpose  events XtAddExposureToRegion(l) 

graphics  expose:  Core  method  for  drawing expose(4) 

a  procedure  to  be  called  on  fatal  error  conditions  /register XtAppSetErrorHandler(1 ) 

a  procedure  to  be  called  on  fatal  error  conditions  /register XtAppSetErrorMsgHandler(1 ) 

a  procedure  to  be  called  on  fatal  error  conditions  /register XtSetErrorHandler(1 ) 

XtAppErrorMsg:  call  the  high-level  fatal  error  handler XtAppErrorMsg(1 ) 

XtError:  call  the  low-level  fatal  error  handler XtError(1) 

XtErrorMsg:  call  the  high-level  fatal  error  handler XtErrorMsg(1 ) 

XtAppError:  call  the  installed  fatal  error  procedure XtAppError(1) 

subparts,/  XtVaGetSubresources:  fetch  resources  for  widget XtVaGetSubresources(1 ) 

/determine  the  byte  offset  of  a  field  within  a  structure  pointer/ XtOffset(1 ) 

/determine  the  byte  offset  of  a  field  within  a  structure  type XtOffsetOf(l) 

of  a  widget's  map_when_managed  field  /change  the  value XtSetMappedWhenManaged(1 ) 

VendorShell:  vendor-specific  shell  fields  and  resources VendorShell(3) 

to  initialize  class  part  structure  fields  /Core  method class_part_initialize(4) 

XtAppAdd Input:  register  a  new  file  as  an  input  source  for  a  given/ XtAppAdd  lnput(  1 ) 

XtAddlnput:  register  a  new  file  as  an  input  source  for  an/ XtAddlnput(1 ) 

/procedure  called  to  handle  file,  pipe,  or  socket  input XtlnputCallbackProc(2) 

or  a/  XtRemovelnput:  unregister  a  file  procedure,  a  pipe  procedure, XtRemovelnput(1 ) 

in/  XtResolvePathname:  search  for  a  file  using  standard  substitutions XtResolvePathname(1 ) 

XtFindFile:  search  for  a  file  using  substitutions  in  a  path XtFindFile(l) 

/prototype  procedure  used  in  filename  evaluation XtFilePredicate(2) 

/and  modifiers  that  matched  the  final  event  specification  in  the/ XtGetActionKeysym(1 ) 

the  number  of  elements  in  a  fixed-size  array  /determine XtNumber(1 ) 

accepting  or  rejecting  the  keyboard  focus  /Core  method  for accept_focus(4) 

implementing  constraints  on/  Form:  geometry-managing  widget Form(5) 

obtain  selection  data  in  multiple  formats  XtGetSelection Values: XtGetSelectionValues(1 ) 

XtFree:  free  an  allocated  block  of  storage XtFree(1 ) 

Release  2  compatible  function  to  free  read-only  GCs  XtDestroyGC: XtDestroyGC(l) 

new  child  XtOrderProc:  Composite  function  to  determine  position  for XtOrderProc(2) 

XtDestroyGC:  Release  2  compatible  function  to  free  read-only  GCs XtDestroyGC(1 ) 
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XtCallbackExclusive:  callback  function  to  pop  up  a  widget XtCallbackExclusive(1 ) 

XtCallbackNone:  callback  function  to  pop  up  a  widget XtCallbackNone(1 ) 

XtCallbackNonexciusive:  callback  function  to  pop  up  a  widget XtCallbackNonexclusive(1 ) 

XtCallbackReleaseCacheRef:  callback  function  to  release  a  cached/ XtCallbackReieaseCacheRef(l) 

cached  values  /callback  function  to  release  a  list  of XtCallbackReleaseCacheRef List(1 ) 

Core:  fundamental  widget Core(3) 

XtReleaseGC:  deallocate  a  shared  GC  when  it  is  no  longer  needed XtReleaseGC(1 ) 

obtain  a  read-only,  shareable  GC  XtGetGC: XtGetGC(1) 

function  to  free  read-only  GCs  /Release  2  compatible XtDestroyGC(l) 

/invoke  an  action  procedure  without  generating  events XtCallActionProc(l) 

Core  method  to  negotiate  compromise  geometries  set_values_almost: set_values_almost(4) 

called  when  a  child  requests  a  new  geometry  /Composite  method geometry_manager(4) 

widget  for  managing  row-column  geometry  List: List(5) 

Composite:  defines  methods  for  geometry  management Composite(3) 

RectObj:  base  class  encapsulating  geometry  management RectObj(3) 

request  parent  to  change  child's  geometry  XtMakeGeometry  Request: XtMakeGeometryRequest(l) 

query  a  child  widget's  preferred  geometry  XtQueryGeometry: XtQueryGeometry(l) 

called  when  a  child  requests  a  new/  geometry  jnanager:  Composite  method geometry _manager(4) 

Box:  geometry-managing  box  widget Box (5) 

vertical  or  horizontal  Paned:  geometry-managing  widget  for Paned(5) 

implementing  constraints  on/  Form:  geometry-managing  widget Form(5) 

XtWidgetToApplicationContext:  get  the  application  context  for  a/ XtWidgetToApplicationContext(1 ) 

XtGetConstraintResourceList:  get  the  constraint  resource  list/ XtGetConstraintResourceLJst(1 ) 

value  XtAppGetSelectionTimeout:  get  the  current  selection  timeout XtApoGetSelectionTimeout(1 ) 

value  XtGetSelectionTimeout:  get  the  current  selection  timeout XtGetSelectionTimeout(l) 

get_values_hook:  Core  method  for  getting  subpart  resource  values get_values_hook(4) 

getting  subpart  resource  values  get_values_hcok:  Core  method  for get_values_hook(4) 

XtGrabKey:  passively  grab  a  single  key  of  the  keyboard XtGrabKey(l) 

XtGrabButton:  passively  grab  a  single  pointer  button XtGrabButton(1 ) 

XtGrabKeyboard:  actively  grab  the  keyboard XtGrabKeyboard(l) 

XtGrabPointer:  actively  grab  the  pointer XtGrabPointer(l)     , 

cancel  a  passive  button  grab  XtUngrabButton: XtUngrabButton(l) 

XtUngrabKey:  cancel  a  passive  key  grab XtUngrabKey(1 ) 

cancel  an  active  keyboard  grab  XtUngrabKey  board: XtUngrabKey  board(1) 

cancel  an  active  pointer  grab  XtUngrabPointer: XtUngrabPointer(l) 

according/  /register  button  and  key  grabs  for  a  widget's  window XtRegisterGrabAction(1 ) 

widget  to  display  a  real-time  graphic  chart  StripChart: StripChart(5) 

expose:  Core  method  for  drawing  graphics expose(4) 

/merge  Expose  and  GraphicsExpose  events  into  a  region XtAddExposureToRegion(l) 

other  widgets  Grip:  attachment  point  for  dragging Grip(5) 

register  a  procedure  to  handle  events  XtAddEventHandler: XtAddEventHandler(1 ) 

/prototype  procedure  called  to  handle  file,  pipe,  or  socket  input XtlnputCallbackProc(2) 

/from  the  most  recent  event  handled  by  XtDispatchEvent  that/ XtLastTimestampProcessed(1 ) 

events  before  or/  /register  an  event  handler  procedure  that  receives XtlnsertRawEventHandler(1 ) 

events  before  or/  /register  an  event  handler  procedure  that  receives XtlnsertEventHandler(1 ) 

XtEventHandler:  prototype  event  handler  procedure XtEventHandler(2) 

event  /register  an  event  handler  without  selecting  for  the XtAddRawEventHandler(1 ) 

call  the  high-level  fatal  error  handler  XtAppErrorMsg: XtAppErrorMsg(l) 

the  installed  high-level  warning  handler  XtAppWamingMsg:  call XtAppWamingMsg(l) 

call  the  low-level  fatal  error  handler  XtError: XtError(1) 

call  the  high-level  fatal  error  handler  XtErrorMsg: XtErrorMsg(l) 

a  previously  registered  event  handler  /remove XtRemoveEventHandler(l) 

remove  a  raw  event  handler  XtRemoveRawEventHandler: XtRemoveRawEventHandler(l) 
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the  installed  low-level  warning  handler  XtWaming:  call XtWaming(1) 

the  installed  high-level  warning  handler  XtWamingMsg:  call XtWamingMsg(1 ) 

/dispatch  registered  handlers  for  an  event XtDispatchEvent(l) 

/all  previously  registered  event  handlers,  without  selecting  for  the/ XtlnsertRawEventHandler(1 ) 

for  low-level  error  and  warning  handlers  XtErrorHandler:  prototype XtErrorHandler(2) 

for  high-level  error  and  warning  handlers  /prototype XtErrorMsgHandler(2) 

all  previously  registered  event  handlers  /events  before  or  after XtlnsertEventHandler(1 ) 

Shell:  top-level  widget  that  handles  application/window  manager/ Shell(3) 

queue  /nondestructive^  examine  the  head  of  an  application's  input XtAppPeekEvent(1 ) 

queue  /nondestructive^  examine  the  head  of  an  application's  input XtPeekEvent(l) 

XtErrorMsgHandler:  prototype  for  high-level  error  and  warning/ XtErrorMsgHandler(2) 

XtAppErrorMsg:  call  the  high-level  fatal  error  handler XtAppErrorMsg(1 ) 

XtErrorMsg:  call  the  high-level  fatal  error  handler XtErrorMsg(1 ) 

XtSetWarningMsgHandler:  register  a  high-level  procedure  to  be  called/ XtSetWamingMsgHandler(1 ) 

XtAppWamingMsg:  call  the  installed  high-level  warning  handler XtAppWamingMsg(1 ) 

XtWamingMsg:  call  the  installed  high-level  warning  handler XtWamingMsg(1 ) 

XtActionHookProc:  prototype  action  hook  procedure XtActionHookProc(2) 

unregister  an  action  hook  procedure  XtRemoveActionHook: XtRemoveActionHook(1 ) 

XtAppAddActionHook:  add  an  action  hook XtAppAddActionHook(1 ) 

widget  for  vertical  or  horizontal  /geometry-managing Paned(5) 

and  display  pointer  into  a  widget  ID  /translate  a  window XtWindowToWidget(l) 

Form:  geometry-managing  widget  implementing  constraints  on/ Form(5) 

/prototype  procedure  to  convert  incremental  selection  data. XtConvertSelectionlncrProc(2) 

/prototype  procedure  to  release  incremental  selection  ownership XtLoseSelectionlncrProc(2) 

/prototype  procedure  to  cancel  incremental  selection  transfer XtCancelConvertSelectionProc(2) 

procedure  to  indicate  completion  of  incremental  transfer  /prototype XtSelectionDonelncrProc(2) 

/obtain  the  selection  value  using  incremental  transfers XtGetSelectionValuelncremental(1 ) 

multiple  selection  values  using  incremental  transfers  /obtain XtGetSelectionValueslncremental(1 ) 

/set  the  selection  owner  when  using  incremental  transfers XtOwnSelectionlncremental(1 ) 

/set  WM_COLORMAP_WINDOWS  property  to  inform  window  manager  of  custom/ XtSetWMColormapWindows(1 ) 

/open  a  display,  and  create  the  initial  application  shell  instance Xt Applnitialize(1 ) 

an/  XtDisplay  Initialize:  initialize  a  display  and  add  it  to XtDisplay Initialize^ ) 

creating/  XtlnitializeWidgetClass:  initialize  a  widget  class  without XtlnitializeWidgetClass(1 ) 

application/  XtOpenDisplay:  open,  initialize,  and  add  a  display  to  an  XtOpenDisplay (1 ) 

fields  /Core  method  to  initialize  class  part  structure class_part_initialize(4) 

Constraint  method  to  initialize  Constraint  initialize: Constraint  initialize^) 

initializing  instance  variables  initialize:  Core  method  for initialize^) 

XtCalloc:  allocate  an  array  and  initialize  elements  to  zero XtCalloc(1) 

create  an/  XtApplnitialize:  initialize  the  X  Toolkit  internals XtApplnitialize(1 ) 

using  varargs/  XtVaApplnitialize:  initialize  the  X  Toolkit  internals XtVaApplnitialize(l) 

XtToolkitlnitialize:  initialize  the  X  Toolkit  internals XtToolkitlnitialize(1 ) 

Xtlnitialize:  initialize  toolkit  and  display Xtlnitialize(1 ) 

initializing  subpart  data  initialize_hook:  Core  method  for initialize_hook(4) 

initialize:  Core  method  for  initializing  instance  variables initialize^) 

initializejiook:  Core  method  for  initializing  subpart  data initialize_hook(4) 

/Core  method  for  dynamically  initializing  the  class class_initialize(4) 

XtAppProcessEvent:  process  one  input  event XtAppProcessEvent(1 ) 

XtProcessEvent:  process  one  input  event XtProcessEvent(t) 

XtAppMainLoop:  process  input  from  a  given  application XtAppMainLoop(1 ) 

normal/  XtRemoveGrab:  redirect  user  input  from  modal  widget  back  to XtRemoveGrab(1 ) 

the  head  of  an  application's  input  queue  /examine XtAppPeekEvent(1 ) 

any  events  are  in  an  application's  input  queue  /determine  whether XtAppPending(l) 

XtNextEvent:  return  next  event  from  input  queue XtNextEvent(1 ) 
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the  head  of  an  application's   input  queue  /examine XtPeekEvent(1 ) 

are  any  events  in  an  application's   input  queue  /determine  if  there XtPending(l) 

/register  a  new  file  as  an   input  source  for  a  given/ XtAppAddlnput(1 ) 

/register  a  new  file  as  an   input  source  for  an  application XtAddlnput(1 ) 

XtAddGrab:  redirect  user  input  to  a  modal  widget XtAddGrab(1) 

child  widget  /redirect  keyboard   input  to  a  normal  descendant  of  a XtSetKeyboardFocus(l) 

to  handle  file,  pipe,  or  socket  input  /prototype  procedure  called XtlnputCallbackProc(2) 

insert_child:  Composite  method  to  insert  a  child  into  the  array  of/ insert_child(4) 

insert  a  child  into  the  array  of/  insert_child:  Composite  method  to insert_child(4) 

another/  XtlnstallAccelerators:   install  a  widget's  accelerators  on XtlnstallAccelerators(l) 

widget/  XtlnstallAIIAccelerators:   install  all  accelerators  from  a XtlnstallAIIAccelerators(l) 

XtAppError:  call  the  installed  fatal  error  procedure XtAppError(1 ) 

handler  XtAppWamingMsg:  call  the  installed  high-level  warning XtAppWamingMsg(l) 

handler  XtWamingMsg:  call  the  installed  high-level  warning XtWamingMsg(l) 

XtWaming:  call  the  installed  low-level  warning  handler XtWaming(1) 

XtAppWaming:  call  the  installed  nonfatal  error  procedure XtAppWarning(l) 

XtName:  return  a  pointer  to  the  instance  name  of  the  specified/ XtName(1 ) 

XtNew:  allocate  storage  for  one  instance  of  a  data  type XtNew(1 ) 

XtNewString:  copy  an   instance  of  a  string XtNewString(1 ) 

XtVaCreateWidget:  create  an   instance  of  a  widget  using  varargs/ XtVaCreateWidget(1 ) 

XtCreateWidget:  create  an   instance  of  a  widget XtCreateWidget(1 ) 

/resources  associated  with  a  widget  instance,  using  varargs  argument/ XtVaGetSubvalues(l) 

/resources  associated  with  a  widget  instance,  using  varargs  argument/ XtVaGetValues(l) 

/resources  associated  with  a  widget  instance,  using  varargs  argument/ XtVaSetSubvalues(1 ) 

/resources  associated  with  a  widget  instance,  using  varargs  argument/ XtVaSetValues(l) 

Core  method  for  initializing   instance  variables  initialize: initialize^) 

the  initial  application  shell   instance  /a  display,  and  create XtApplnitialize(l) 

XtDestroy  Widget:  destroy  a  widget  instance XtDestroyWidget(l) 

translate  a  widget  name  to  a  widget  instance  XtNameToWidget: XtNameToWidget(1 ) 

XtRealizeWidget:  realize  a  widget  instance XtRealizeWidget(l) 

handles  application/window  manager  interaction  /top-level  widget  that Shell(3) 

an  accelerator  table  into  its   internal  representation  /compile XtParseAcceleratorTaWe(l) 

a  translation  table  into  its   internal  representation  /compile XtParseTranslationTaWe(l) 

context,/  /initialize  the  X  Toolkit   internals,  create  an  application XtApplnitialize(1 ) 

style  /initialize  the  X  Toolkit  internals,  using  varargs  argument XtVaApplnitialize(1 ) 

initialize  the  X  Toolkit  internals  XtToolkitlnitialize: XtToolkitlnitialize(l) 

XtAppSetSelectionTimeout:  set  the   Intrinsics  selection  timeout XtAppSetSelectionTimeout(1 ) 

mapping  table  maintained  by  the   Intrinsics  /keysym  in  the  keyboard XtKeysymToKeycodeList(l) 

SmeLine:  menu   item  separator SmeLine(5) 

XtUngrabKey:  cancel  a  passive  key  grab XtUngrabKey(l) 

according  to/  /register  button  and  key  grabs  for  a  widget's  window XtRegisterGrabAction(1 ) 

XtGrabKey:  passively  grab  a  single  key  of  the  keyboard XtGrabKey(1 ) 

XtSetKeyTranslator:  register  a  key  translator XtSetKeyTranslator(1 ) 

prototype  procedure  to  translate  a  key  XtKeyProc: XtKeyProc(2) 

for  accepting  or  rejecting  the  keyboard  focus  /Core  method accept_focus(4) 

XtUngrabKeyboard:  cancel  an  active  keyboard  grab XtUngrabKeyboard(1 ) 

XtSetKeyboardFocus:  redirect  keyboard  input  to  a  normal/ XtSetKeyboardFocus(l) 

/map  to  a  particular  keysym  in  the   keyboard  mapping  table  maintained/ XtKeysymToKeycodeLJst(1 ) 

passively  grab  a  single  key  of  the  keyboard  XtGrabKey: XtGrabKey(l) 

XtGrabKeyboard:  actively  grab  the  keyboard XtGrabKeyboard(l) 

keysym  in  the/  /return  the  list  of  keycodes  that  map  to  a  particular XtKeysymToKeycodeLJst(1 ) 

XtTranslateKey:  the  default  keycode-to-keysym  translator XtTranslateKey(l) 

/invoke  the  currently  registered   keycode-to-keysym  translator XtTranslateKeycode(1 ) 
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XtGetActionKeysym:  retrieve  the  keysym  and  modifiers  that  matched/ XtGetActionKeysym(l) 

keycodes  that  map  to  a  particular  keysym  in  the  keyboard  mapping/  /of XtKeysymToKeycodeList(l) 

and  lower-case  versions  of  a  keysym  /determine  upper-case XtConvertCase(l) 

called  to  convert  the  case  of  keysyms  /prototype  procedure XtCaseProc(2) 

a/  /return  a  pointer  to  the  keysym-to-keycode  mapping  table  for XtGetKeysymTable(1 ) 

non-editable  string   Label:  widget  to  display  a Label(5) 

WMShell:  application  resources   linking  window  managers WMShell(3) 

list,  specifying  the  callback  list  by  address  /in  a  callback XtCallCallbacklJst(l) 

XtSetArg:  modify  an  argument  list  dynamically XtSetArg(1) 

is  specified  in  a  resource  list  entry  /when  XtRCallProc XtResourceDefaultProc(2) 

/dynamically  allocate  a  varargs   list  for  use  with  the/ XtVaCreateArgsUst(1 ) 

/callback  function  to  release  a  list  of  cached  values XtCallbackReleaseCacheRefList(1 ) 

given/  XtAddCallbacks:  add  a  list  of  callback  procedures  to  a XtAddCallbacks(1 ) 

XtUnmanageChildren:  remove  a  list  of  children  from  a  parent/ XtUnmanageChildren(1 ) 

XtKeysymToKeycodeLJst:  return  the  list  of  keycodes  that  map  to  a/ XtKeysymToKeycodeList(1 ) 

/add  a  widget  to  its  parent's  list  of  managed  children XtManageChild(1 ) 

/add  widgets  to  their  parent's   list  of  managed  children XtManageChildren(1 ) 

method  to  respond  to  a  change  in  a  list  of  managed  widgets  /Composite change_managed(4) 

list  XtRemoveCallbacks:  delete  a  list  of  procedures  from  a  callback XtRemoveCallbacks(1 ) 

by/  /the  procedures  in  a  callback  list,  specifying  the  callback  list XtCallCallbackList(l) 

widget/  /get  the  constraint  resource   list  structure  for  a  particular XtGetConstraintResourceList(1 ) 

row-column  geometry   List:  widget  for  managing List(5) 

to  a  given  widget's  callback  list  /a  list  of  callback  procedures XtAddCallbacks(1 ) 

procedures  in  a  widget's  callback  list  XtCallCallbacks:  execute  the XtCallCallbacks(1 ) 

default  values  for  a  resource  list  XtGetResourceList:  retrieve XtGetResourceList(l) 

update  subpart  resource  list.  XtGetSubresources: XtGetSubresources(1 ) 

data  structure  to  the  argument  list  /copy  from  subpart XtGetSubvalues(t) 

from  a  widget  to  the  argument  list  XtGetValues:  copy  resources XtGetValues(l) 

the  status  of  a  widget's  callback  list  XtHasCallbacks:  determine XtHasCallbacks(l) 

all  procedures  from  a  callback  list  XtRemoveAIICallbacks:  delete XtRemoveAIICallbacks(1 ) 

delete  a  procedure  from  a  callback  list  XtRemoveCallback: XtRemoveCallback(1 ) 

list  of  procedures  from  a  callback  list  XtRemoveCallbacks:  delete  a XtRemoveCallbacks(l) 

standard  substitutions  in  a  path   list  /search  for  a  file  using XtResolvePathname(l) 

an  ArgList  to  a  subpart  resource  list  /copy  resource  settings  from XtSetSubvalues(1 ) 

a  widget  from  its  parent's  managed   list  XtUnmanageChild:  remove XtUnmanageChild(1 ) 

from  a  parent  widget's  managed   list  /remove  a  list  of  children XtUnmanageChildren(1 ) 

converter,/  XtConvertAndStore:   look  up  and  call  a  resource XtConvertAndStore(l) 

/determine  upper-case  and   lower-case  versions  of  a  keysym XtConvertCase(1 ) 

XtErrorHandler:  prototype  for  low-level  error  and  warning/ XtErrorHandler(2) 

XtError:  call  the  low-level  fatal  error  handler XtError(1 ) 

XtWaming:  call  the  installed   low-level  warning  handler XtWarning(1 ) 

ApplicationShell:   main  shell  for  an  application ApplicationShell(3) 

XtVaCreateManagedWidget:  create  and   manage  a  child  widget  in  a  single/ XtVaCreateManagedWidget(1 ) 

XtCreateManagedWidget:  create  and   manage  a  child  widget XtCreateManagedWidget(1 ) 

determine  whether  a  widget  is   managed  by  its  parent  XtlsManaged: XtlsManaged(l) 

a  widget  to  its  parent's  list  of  managed  children  /add XtManageChild(l) 

widgets  to  their  parent's  list  of  managed  children  /add XtManageChildren(l) 

remove  a  widget  from  its  parent's   managed  list  XtUnmanageChild: Xtl)nmanageChild(l) 

of  children  from  a  parent  widget's   managed  list  /remove  a  list XtUnmanageChildren(1 ) 

to  respond  to  a  change  in  a  list  of  managed  widgets  /Composite  method change_managed(4) 

base  class  encapsulating  resource  management  and  callbacks  Object: Object(3) 

defines  methods  for  geometry   management  Composite: Composite(3) 

pop-up  shell  that  bypasses  window  management  OvemdeShell: OverrideShell(3) 
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base  class  encapsulating  geometry  management  RectObj: RectObj(3) 

shell  that  doesn't  bypass  window  management  TransientShell:  pop-up TransientShell(3) 

that  handles  application/window  manager  interaction  /widget Shell(3) 

/property  to  inform  window  manager  of  custom  colormaps XtSetWMColormapWindows(1 ) 

action  table  with  the  Translation  Manager  Xt  Add  Act  ions:  register  an XtAddActions(l) 

and  register  it  with  the  Resource  Manager  /declare  an  action  table XtAppAddActions(l) 

resources  linking  window  managers  WMShell:  application WMShell(3) 

List:  widget  for  managing  row-column  geometry LJst(5) 

XtPopup:  map  a  pop-up  shell XtPopup(1 ) 

within  an/  XtPopupSpringLoaded:  map  a  spring-loaded  pop-up  from XtPopupSpringLoaded(1 ) 

XtMapWidget:  map  a  widget  to  its  display XtMapWidget(1 ) 

/return  the  list  of  keycodes  that  map  to  a  particular  keysym  in  the/ XtKeysymToKeycodeList(1 ) 

la  pointer  to  the  keysy m-to-key code  mapping  table  for  a  particular/ XtGetKeysy mTable(1 ) 

a  particular  keysym  in  the  keyboard  mapping  table  maintained  by  the/  /to XtKeysymToKeycodeList(l) 

/change  the  value  of  a  widget's  map_when_managed  field XtSetMapoedWhenManaged(1 ) 

retrieve  a  widget's  event  mask  XtBuildEventMask: XtBuildEventMask(l) 

the  keysym  and  modifiers  that  matched  the  final  event/  /retrieve XtGetActionKeysym(l) 

SimpleMenu:  menu  container  widget SimpleMenu(5) 

Sme:  base  class  for  menu  entries Sme(5) 

SmeBSB:  basic  menu  entry SmeBSB(5) 

SmeLine:  menu  item  separator SmeLine(5) 

MenuButton:  button  which  pops  up  a  menu MenuButton(S) 

menu  MenuButton:  button  which  pops  up  a MenuButton(S) 

events  into/  XtAddExposureToRegion:  merge  Expose  and  GraphicsExpose XtAddExposureToRegion(l) 

widget's/  XtOverrideTranslations:  merge  new  translations,  overwriting XtOverrideTranslations(1 ) 

widget's  existing/  /nondestructive^  merge  new  translations  with XtAugmentTranslations(l) 

XtMergeArgLJsts:  merge  two  ArgList  structures XtMergeArgLJsts(l) 

resource  values  /issue  a  warning  message  during  conversion  of  string XtDisplayStringConversionWarning(1 ) 

boilerplate  string  conversion  error  message  /emit XtStringConversionWaming(1 ) 

destroyed  delete_child:  Composite  method  called  when  a  child  is delete_child(4) 

a  new/  geometryjnanager:  Composite  method  called  when  a  child  requests geometry_manager(4) 

destroyed  destroy:  Core  method  called  when  a  widget  is destroy(4) 

destroyed  query_geometry:  Core  method  called  when  a  widget  is query_jeometry(4) 

resized  resize:  Core  method  called  when  a  widget  is resize(4) 

the  keyboard/  acceptjocus:  Core  method  for  accepting  or  rejecting accept_focus(4) 

Constraint  destroy:  Constraint  method  for  cleaning  up  after  a/ Constraint  destroy (4) 

expose:  Core  method  for  drawing  graphics expose(4) 

the  class  classjnitialize:  Core  method  for  dynamically  initializing class_initialize(4) 

values  get_yalues_hook:  Core  method  for  getting  subpart  resource get_values_hook(4) 

variables  initialize:  Core  method  for  initializing  instance initialize^) 

data  initialize_hook:  Core  method  for  initializing  subpart initialize_hook(4) 

Constraint  set_values:  Constraint  method  for  processing  constraint/ Constraint  set_values(4) 

changes  set_values:  Core  method  for  processing  resource set_values(4) 

resources  set_values_hook:  Core  method  for  processing  subpart set_values_hook(4) 

display_accelerator:  Core  method  to  display  current/ display_accelerator(4) 

class_partjnitialize:  Core  method  to  initialize  class  part/ class_part_initialize(4) 

Constraint  initialize:  Constraint  method  to  initialize Constraint  initialize^) 

array  of/  insert_child:  Composite  method  to  insert  a  child  into  the insert_child(4) 

geometries  set_values_almost:  Core  method  to  negotiate  compromise set_values_almost(4) 

list  of/  changejnanaged:  Composite  method  to  respond  to  a  change  in  a change_managed(4) 

create  window  realize:  Core  method  to  set  window  attributes  and realize(4) 

Composite:  defines  methods  for  geometry  management Composite(3) 

/redirect  user  input  from  modal  widget  back  to  normal/ XtRemoveGrab(1 ) 
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XtAddGrab:  redirect  user  input  to  a 

XtCheckSubclass:  in  DEBUG 

event/  /retrieve  the  keysym  and 

XtSetArg: 

resources/  XtVaSetValues: 

XtMoveWidget: 

XtConfigureWidget: 

XtSetMultiClickTime:  set  the 

XtGetMultiClickTime:  read  the 

/obtain  selection  data  in 

incremental  transfers  /obtain 

with  the  XtVaNestedLJst  symbol  in 

/return  the  application 

/return  a  pointer  to  the  instance 

XtNameToWidget:  translate  a  widget 

set_values_almost:  Core  method  to 

function  to  determine  position  for 

given/  XtAppAddlnput:  register  a 

application  XtAddlnput:  register  a 

called  when  a  child  requests  a 

XtAppAddConverter:  register  a 

XtAddConverter:  register  a 

XtOverrideTranslations:  merge 

existing/  /nondestructive!/  merge 

/prototype  procedure  for  a 

event  queue  XtAppNextEvent:  return 

XtNextEvent:  return 

of  an/  XtAppPeekEvent: 

of  an  application's/  XtPeekEvent: 

XtAugmentTranslations: 

Label:  widget  to  display  a 

a  procedure  to  be  called  on 

/a  procedure  to  be  called  on 

a  procedure  to  be  called  on 

a  procedure  to  be  called  on 

/procedure  to  be  called  on 

XtAppWaming:  call  the  installed 

a/  /retrieve  the  current  values  of 

a  widget/  /set  the  current  values  of 

/redirect  keyboard  input  to  a 

input  from  modal  widget  back  to 

array  XtNumber:  determine  the 

resource  management  and  callbacks 

/pointer  for  the  nearest  ancestor  of 

/pointer  for  the  nearest  ancestor  of 

window  for  the  nearest  ancestor  of 

a  widget  is  a  subclass  of  the 

the  instance  name  of  the  specified 

in  DEBUG  mode,  verify  an 

XtGetGC: 

XtClass: 

XtSuperclass: 

XtGetSelectionValueslncremental: 


modal  widget XtAddGrab(1) 

mode,  verify  an  object's  class XtCheckSubclass(1 ) 

modifiers  that  matched  the  final XtGetActionKeysym(l) 

modify  an  argument  list  dynamically XtSetArg(1) 

modify  the  current  values  of XtVaSetValues(l) 

move  a  widget  on  the  display XtMoveWidget(1 ) 

move  and/or  resize  widget XtConfigureWidget(l) 

multi-click  time  dynamically XtSetMultiClickTime(1 ) 

multi-click  time XtGetMultiClickTime(1 ) 

multiple  formats XtGetSelectionValues(1 ) 

multiple  selection  values  using XtGetSelectionValueslncremental(1 ) 

multiple  varargs  calls  /for  use XtVaCreateArgsList(1 ) 

name  and  class  as  passed  to/ XtGetApplicationNameAndClass(l) 

name  of  the  specified  object XtName(1 ) 

name  to  a  widget  instance XtNameToWidget(1 ) 

negotiate  compromise  geometries set_values_almost(4) 

new  child  XtOrderProc:  Composite XtOrderProc(2) 

new  file  as  an  input  source  for  a XtAppAddlnput(1 ) 

new  file  as  an  input  source  for  an XtAddlnput(l) 

new  geometry  /Composite  method geometry_manager(4) 

new  resource  converter  for  an/ XtAppAddConverter(1 ) 

new  resource  converter XtAddConverter(l) 

new  translations,  overwriting/ XtOverrideTranslations(l) 

new  translations  with  widget's XtAugmentTranslations(1 ) 

new-style  resource  converter XtTypeConverter(2) 

next  event  from  an  application's  X XtAppNextEvent(1 ) 

next  event  from  input  queue XtNextEvent(t) 

nondestructive^  examine  the  head XtAppPeekEvent(l) 

nondestructive^  examine  the  head XtPeekEvent(l) 

nondestructive^  merge  new/ XtAugmentTranslations(l) 

non-editable  string Label(5) 

nonfatal  error  conditions  /register XtAppSetWarningHandler(l) 

nonfatal  error  conditions XtAppSetWamingMsgHandler(1 ) 

nonfatal  error  conditions  /register XtSetErrorMsgHandler(l) 

nonfatal  error  conditions  /register XtSetWamingHandler(l) 

nonfatal  error  conditions XtSetWamingMsgHandler(l) 

nonfatal  error  procedure XtAppWaming(l) 

nonwidget  resources  associated  with XtVaGetSubvalues(l) 

nonwidget  resources  associated  with XtVaSetSubvalues(1 ) 

normal  descendant  of  a  child  widget XtSetKeyboardFocus(1 ) 

normal  destination  /redirect  user XtRemoveGrab(1 ) 

number  of  elements  in  a  fixed-size XtNumber(1) 

Object:  base  class  encapsulating Object(3) 

object  that  is  of  class  Widget XtDisplayOfObject(1 ) 

object  that  is  of  class  Widget XtScreenOfObject(l) 

object  that  is  of  class  Widget  /the XtWindowOfObject(1 ) 

Object  widget  class  /test  whether XtlsObject(1 } 

object  XtName:  return  a  pointer  to XtName(1 ) 

object's  class  XtCheckSubclass: XtCheckSubclass(l) 

obtain  a  read-only,  shareable  GC XtGetGC(1) 

obtain  a  widget's  class XtClass(1) 

obtain  a  widget's  superclass XtSuperclass(l) 

obtain  multiple  selection  values/ XtGetSelectionValueslncremental(1 ) 
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formats  XiGetSelection Values: 

XtGetSelectionValue: 

an/  XtAppGetErrorDatabaseText: 

an  error/  XtGetErrorDatabaseText: 

XtAppGetErrorOatabase : 

XtGetErrorOatabase: 

particular  display  XtDatabase: 

XtGetSelectionValuelncremental: 

/counts  for  cached  resources 

XtOffset:  determine  the  byte 

XtOffsetOf:  determine  the  byte 

/create  an  application  context, 

to  an  application/  XtOpen Display: 

/retrieve  resources  for  the 

bypasses  window  management 

a  widget  is  a  subclass  of  the 

/merge  new  translations, 

transfers  /set  the  selection 

to  release  incremental  selection 

root/  /translate  an  x-y  coordinate 

vertical  or  horizontal 

data  structures  for  a  widget's 

XtMakeGeometryRequest:  request 

XtMakeResizeRequest:  request 

widget  XtParent:  return  the 

/remove  a  list  of  children  from  a 

whether  a  widget  is  managed  by  its 

XtManageChild:  add  a  widget  to  its 

/add  widgets  to  their 

/remove  a  widget  from  its 

/Core  method  to  initialize  class 

XtRCallProc  is/  /prototype  procedure 

/the  application  name  and  class  as 

XtUngrabButton:  cancel  a 

XtUngrabKey:  cancel  a 

keyboard  XtGrabKey: 

button  XtGrabButton: 

using  standard  substitutions  in  a 

for  a  file  using  substitutions  in  a 

cache  result  XtDirectConvert: 

XtWorkProc:  prototype  procedure  for 

procedure  called  to  handle  file, 

/unregister  a  file  procedure,  a 

Grip:  attachment 

passively  grab  a  single 

command  button  activated  by 

object  that  is/  /return  the  display 

XtScreenOfObject:  return  the  screen 

XtOisplay:  return  the  display 

XtScreen:  return  the  screen 

XtUngrabPointer:  cancel  an  active 

/translate  a  window  and  display 

specified  object  XtName:  return  a 


obtain  selection  data  in  multiple XtGetSelectionValues(l) 

obtain  the  complete  selection  data XtGetSelectionValue(1 ) 

obtain  the  error  database  text  for XtAppGetErrorDatabaseText(l) 

obtain  the  error  database  text  for XtGetErrorDatabaseText(l) 

obtain  the  error  database XtAppGetErrorOatabase(1 ) 

obtain  the  error  database XtGetErrorDatabase(1 ) 

obtain  the  resource  database  for  a XtDatabase(l) 

obtain  the  selection  value  using/ XtGetSelectionValuelncremental(1 ) 

obtained  from  XtCallConverter XtAppReleaseCacheRefs(l) 

offset  of  a  field  within  a/ XtOffset(1) 

offset  of  a  field  within  a/ XtOffsetOf(l) 

open  a  display,  and  create  the/ XtApplnitialize(l) 

open,  initialize,  and  add  a  display XtOpenDisplay(l) 

overall  application  using  varargs/ XtVaGetApplicationResources(l) 

OverrideShell:  pop-up  shell  that OverrideShell(3) 

OverrideShell  widget  class  /whether XtlsOverrideShell(l) 

overwriting  widget's  existing  ones XtOverrideTranslations(1 ) 

owner  when  using  incremental XtOwnSelectionlncremental(l) 

ownership  /prototype  procedure XtLoseSelectionlncrProc(2) 

pair  from  widget  coordinates  to XtTranslateCoords(l) 

Paned:  geometry-managing  widget  for Paned(5) 

parent  Constraint:  provides Constraint^) 

parent  to  change  child's  geometry XtMakeGeometryRequest(t) 

parent  to  change  child's  size XtMakeResizeRequest(l) 

parent  widget  for  the  specified XtParent(1) 

parent  widget's  managed  list XtUnmanageChildren(1 ) 

parent  XtlsManaged:  determine XtlsManaged(l) 

parent's  list  of  managed  children XtManageChild(  1 ) 

parent's  list  of  managed  children XtManageChildren(l) 

parent's  managed  list XtUnmanageChild(l) 

part  structure  fields class_part_initialize(4) 

passed  as  a  resource  converter  when XtResourceDefaultP'roc(2) 

passed  to  XtDisplay  Initialize  for  a/ XtGetApplicationNameAndClass(l) 

passive  button  grab XtUngrabButton(l) 

passive  key  grab XtUngrabKey (1) 

passively  grab  a  single  key  of  the XtGrabKey(l) 

passively  grab  a  single  pointer XtGrabButton(1 ) 

path  list  /search  for  a  file XtResolvePathname(l) 

path  XtFindFile:  search XtFindFile(l) 

perform  resource  conversion  and XtDirectConvert(l) 

performing  background  processing XtWorkProc(2) 

pipe,  or  socket  input  /prototype XtlnputCallbackProc(2) 

pipe  procedure,  or  a  socket/ XtRemovelnput(l) 

point  for  dragging  other  widgets Grip(5) 

pointer  button  XtGrabButton: XtGrabButton(l) 

pointer  click  Command: Command(5) 

pointer  for  the  nearest  ancestor  of XtOisplayOfObject(l) 

pointer  for  the  nearest  ancestor  of/ XtScreenOfObject(l) 

pointer  for  the  specified  widget XtDisplay(l) 

pointer  for  the  specified  widget XtScreen(1) 

pointer  grab XtUngrabPointer(l) 

pointer  into  a  widget  ID XtWindowToWidget(1 ) 

pointer  to  the  instance  name  of  the XtName(1 ) 
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mapping/  XtGetKeysymTaWe:  return  a  pointer  to  the  keysym-to-keycode XtGetKeysymTable(1 ) 

of  a  field  within  a  structure  pointer  type  /the  byte  offset XtOffset(1 ) 

XtGrabPointer:  actively  grab  the   pointer XtGrabPointer(1) 

routine  XtCallbackPopdown:   pop  down  a  widget  from  a  callback XtCallbackPopdown(1 ) 

/callback  function  to  pop  up  a  widget XtCallbackExclusive(1 ) 

callback  function  to  pop  up  a  widget  XtCallbackNone: XtCallbackNone(1 ) 

/callback  function  to  pop  up  a  widget XtCallbackNonexclusive(1 ) 

XtMenuPopdown:  built-in  action  for  popping  down  a  widget XtMenuPopdown(l) 

XtMenuPopup:  built-in  action  for  popping  up  a  widget XtMenuPopup(1) 

MenuButton:  button  which   pops  up  a  menu MenuButton(S) 

/map  a  spring-loaded   pop-up  from  within  an  application XtPopupSpringLoaded(1 ) 

management  OverrideShell:   pop-up  shell  that  bypasses  window OverrideShell(3) 

window  management  TransientShell:   pop-up  shell  that  doesn't  bypass TransientShell(3) 

XtVaCreatePopupShell:  create  a  pop-up  shell,  using  varargs/ XtVaCreatePopupShell(1 ) 

XtCreatePopupShell:  create  a  pop-up  shell XtCreatePopupShell(1 ) 

XtPopdown:  unmapa  pop-up  shell XtPopdown(l) 

XtPopup:  map  a  pop-up  shell XtPopup(1) 

/Composite  function  to  determine  position  for  new  child XtOrderProc(2) 

/query  a  child  widget's   preferred  geometry XtQueryGeometry(1 ) 

XtRemoveEventHandler:  remove  a  previously  registered  event  handler XtRemoveEventHandler(l) 

receives  events  before  or  after  all   previously  registered  event/  /that XtlnsertRawEventHandler(1 ) 

receives  events  before  or  after  all   previously  registered  event/  rthat XtlnsertEventHandler(1 ) 

XtRemovelnput:  unregister  a  file  procedure,  a  pipe  procedure,  or  a/ XtRemovelnput(1 ) 

XtAppAddTimeOut:  invoke  a  procedure  after  a  specified  timeout XtAppAddTimeOut(1 ) 

XtSelectionDoneProc:  prototype  procedure  called  after  a  data/ XtSelectionDoneProc(2) 

XtLoseSelectionProc:  prototype  procedure  called  by  Xt  when  another/ XtLoseSelectionProc(2) 

case  of/  XtCaseProc:  prototype  procedure  called  to  convert  the XtCaseProc(2) 

XtlnputCallbackProc:  prototype  procedure  called  to  handle  file,/ XtlnputCallbackProc(2) 

XtSelectionCallbackProc:  prototype  procedure  called  when  requested/ XtSelectionCallbackProc(2) 

XtAppAddWorkProc:  register  a  work  procedure  for  a  given  application XtAppAddWorkProc(1 ) 

XtTypeConverter:  prototype  procedure  for  a  new-style  resource/ XtTypeConverter(2) 

XtAddWorkProc:  register  a  work  procedure  for  an  application XtAddWorkProc(1 ) 

XtConvertArgProc:  prototype  procedure  for  argument  conversion XtConvertArgProc(2) 

processing  XtWorkProc:  prototype  procedure  for  performing  background XtWorkProc(2) 

XtRemoveCallback:  delete  a  procedure  from  a  callback  list XtRemoveCallback(l) 

expire  /prototype  callback  procedure  invoked  when  timeouts XtTimerCallbackProc(2) 

/unregister  a  file  procedure,  a  pipe  procedure,  or  a  socket  procedure XtRemovelnput(1 ) 

XtResourceDefaultProc:  prototype  procedure  passed  as  a  resource/ XtResourceDefaultProc(2) 

before/  /register  an  event  handler  procedure  that  receives  events XtlnsertRawEventHandler(1 ) 

before/  /register  an  event  handler  procedure  that  receives  events XtlnsertEventHandler(1 ) 

XtAddCallback:  add  a  callback  procedure  to  a  widget's  callback/ XtAddCallback(l) 

XtAppSetErrorHandler:  register  a  procedure  to  be  called  on  fatal/ XtAppSetErrorHandler(1 ) 

XtAppSetErrorMsgHandter:  register  a  procedure  to  be  called  on  fatal/ XtAppSetErrorMsgHandler(1 ) 

XtSetErrorHandler:  register  a  procedure  to  be  called  on  fatal/ XtSetErrorHandler(1 ) 

XtAppSetWamingHandler:  register  a  procedure  to  be  called  on  nonfatal/ XtAppSetWamingHandler(l) 

error  conditions,  /register  a  procedure  to  be  called  on  nonfatal XtAppSetWamingMsgHandler(1 ) 

XtSetErrorMsgHandler:  register  a  procedure  to  be  called  on  nonfatal/ XtSetErrorMsgHandler(1 ) 

XtSetWamingHandler:  register  a  procedure  to  be  called  on  nonfatal/ XtSetWamingHandler(l) 

error/  /register  a  high-level  procedure  to  be  called  on  nonfatal XtSetWamingMsgHandler(l) 

selection  transfer  /prototype  procedure  to  cancel  incremental XtCancelConvertSelectionProc(2) 

selection  data  /prototype  procedure  to  convert  incremental XtConvertSelectionlncrProc(2) 

XtConvertSelectionProc:  prototype  procedure  to  convert  selection  data XtConvertSelectionProc(2) 

resource/  XtDestructor:  prototype  procedure  to  destroy  cached XtDestructor(2) 
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XtAddEventHandler:  register  a 

XtSelectionDonelncrProc:  prototype 

XtLoseSelectionlncrProc:  prototype 

XtKeyProc:  prototype 

XtFilePredicate:  prototype 

/manage  a  child  widget  in  a  single 

XtCallActionProc:  invoke  an  action 

prototype  action  hook 

XtActionProc:  prototype  action 

call  the  installed  fatal  error 

call  the  installed  nonfatal  error 

call  a  widget's  acceptjocus 

XtCallbackProc:  prototype  callback 

prototype  of  a  resource  converter 

prototype  event  handler 

triggered  the  convert_selection 

unregister  an  action  hook 

a  pipe  procedure,  or  a  socket 

unregister  a  timeout 

XtRemoveWorkProc:  unregister  a  work 

XtRemoveAIICallbacks:  delete  all 

XtRemoveCallbacks:  delete  a  list  of 

XtCallCallbackLJst:  execute  the 

list  XtCallCallbacks:  execute  the 

callback/  /add  a  list  of  callback 

XtMainLoop:  continuously 

application  XtAppMainLoop: 

XtAppProcessEvent: 

XtProcessEvent: 

for  all  application  contexts  in  a 

changes  /Constraint  method  for 

set_values:  Core  method  for 

set_values_hook:  Core  method  for 

procedure  for  performing  background 

of  custom/  /set  WM_COLORMAP_WINDOWS 

XtActionHookProc: 

XtActionProc: 

invoked  when/  XtTimerCallbackProc: 

XtCallbackProc: 

XtEventHandler: 

warning/  XtErrorMsgHandler: 

warning  handlers  XtErrorHandler: 

procedure  XtConverter: 

data  transfer/  XtSelectionDoneProc: 

when  another/  XtLoseSelectionProc: 

convert  the  case  of/  XtCaseProc: 

handle  file,/  XtlnputCallbackProc: 

requested/  XtSelectionCallbackProc: 

resource/  XtTypeConverter: 

conversion.  XtConvertArgProc: 

background  processing  XtWorkProc: 

resource/  XtResourceDefaultProc: 

XtCancelConvertSelectionProc: 


procedure  to  handle  events XtAddEventHandler(l) 

procedure  to  indicate  completion  of/ XtSelectionDonelncrProc(2) 

procedure  to  release  incremental/ XtLoseSelectionlncrProc(2) 

procedure  to  translate  a  key XtKeyProc(2) 

procedure  used  in  filename/ XtFilePredicate(2) 

procedure,  using  varargs  argument/ XtVaCreateManagedWidget(1 ) 

procedure  without  generating  events XtCallActionProc(l) 

procedure.  XtActionHookProc: XtActionHookProc(2) 

procedure XtActionProc(2) 

procedure  XtAppError: XtAppError(l) 

procedure  XtAppWaming: XtAppWaming(l) 

procedure  XtCallAcceptFocus: XtCallAcceptFocus(l) 

procedure XtCallbackProc(2) 

procedure  XtConverter: XtConverter(2) 

procedure.  XtEventHandler: XtEventHandler(2) 

procedure  /event  that XtGetSelectionRequest(l) 

procedure  XtRemoveActionHook: XtRemoveActionHook(1 ) 

procedure  /a  file  procedure XtRemovelnput(l) 

procedure  XtRemoveTimeOut: XtRemoveTimeOut(l) 

procedure XtRemoveWorkProc(1 ) 

procedures  from  a  callback  list XtRemoveAIICallbacks(1 ) 

procedures  from  a  callback  list XtRemoveCallbacks(l) 

procedures  in  a  callback  list,/ XtCallCallbackList(l) 

procedures  in  a  widget's  callback XtCallCallbacks(l) 

procedures  to  a  given  widget's XtAddCallbacks(l) 

process  events XtMainLoop(1) 

process  input  from  a  given XtAppMainLoop(1) 

process  one  input  event XtAppProcessEvent(l) 

process  one  input  event XtProcessEvent(l) 

process,  /register  a  type  converter XtSetTypeConverter(1 ) 

processing  constraint  resource Constraint  set_values(4) 

processing  resource  changes set_yalues(4)      ' 

processing  subpart  resources set_values_hook(4) 

processing  XtWorkProc:  prototype XtWorkProc(2) 

property  to  inform  window  manager XtSetWMColormapWindows(l) 

prototype  action  hook  procedure XtActionHcokProc(2) 

prototype  action  procedure XtActionProc(2) 

prototype  callback  procedure XtTimerCallbackProc(2) 

prototype  callback  procedure XtCallbackProc(2) 

prototype  event  handler  procedure XtEventHandler(2) 

prototype  for  high-level  error  and XtErrorMsgHandler(2) 

prototype  for  low-level  error  and XtErrorHandler(2) 

prototype  of  a  resource  converter XtConverter(2) 

prototype  procedure  called  after  a XtSelectionDoneProc(2) 

prototype  procedure  called  by  Xt XtLoseSelectionProc(2) 

prototype  procedure  called  to XtCaseProc(2) 

prototype  procedure  called  to XtlnputCallbackProc(2) 

prototype  procedure  called  when XtSelectionCallbackProc(2) 

prototype  procedure  for  a  new-style XtTypeConverter(2) 

prototype  procedure  for  argument XtConvertArgProc(2) 

prototype  procedure  for  performing XtWorkProc(2) 

prototype  procedure  passed  as  a XtResourceDefaultProc(2) 

prototype  procedure  to  cancel/ XtCancelConvertSelectionProc(2) 
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XtConvertSelectionlncrProc: 

selection/  XtConvertSelectionProc: 

cached  resource  data  XtDestructor: 

XtSelectionDonelncrProc: 

XtLoseSelectionlncrProc: 

key  XtKeyProc: 

filename/  XtFilePredicate: 

geometry  XtQueryGeometry: 

when  a  widget  is  destroyed 

event  from  an  application's  X  event 

the  head  of  an  application's  input 

are  in  an  application's  input 

return  next  event  from  input 

the  head  of  an  application's  input 

events  in  an  application's  input 

XtRemoveRawEventHandler:  remove  a 

XtGetMultiClickTime: 

2  compatible  function  to  free 

XtGetGC:  obtain  a 

XtRealizeWidget: 

attributes  and  create  window 

determine  whether  a  widget  has  been 

StripChart:  widget  to  display  a 

/an  event  handler  procedure  that 

/an  event  handler  procedure  that 

the  timestamp  from  the  most 

geometry  management 

a  widget  is  a  subclass  of  the 

descendant  of/  XtSet  Key  board  Focus: 

widget  back  to/  XtRemoveGrab: 

widget  XtAddGrab: 

resources/  /explicitly  decrement  the 

and  GraphicsExpose  events  into  a 

XtRegisterCaseConverter: 

be  called/  XtSetWarningMsgHandler: 

XtSetKeyTranslator: 

source  for  a  given/  XtAppAddlnput: 

source  for  an/  XtAddlnput: 

for  an/  XtAppAddConverter: 

XtAddConverter: 

on  fatal/  XtAppSetErrorHandler: 

on  fatal/  XtAppSetErrorMsgHandler: 

on  fatal  error/  XtSetErrorHandler: 

on/  XtAppSelWarningHandler: 

on/  XtAppSetWarningMsgHandler: 

on  nonfatal/  XtSetErrorMsgHandler: 

on  nonfatal/  XtSetWarningHandler: 

events  XtAddEventHandler: 

application/  XtSetTypeConverter: 

single/  XtAppSetTypeConverter: 

given/  XtAppAddWorkProc: 

application  XtAddWorkProc: 

Translation  Manager  XtAddActions: 


prototype  procedure  to  convert/ XtConvertSelectionlncrProc(2) 

prototype  procedure  to  convert XtConvertSelectionProc(2) 

prototype  procedure  to  destroy XtDestructor(2) 

prototype  procedure  to  indicate/ XtSelectionDonelncrProc(2) 

prototype  procedure  to  release/ XtLoseSelectionlncrProc(2) 

prototype  procedure  to  translate  a XtKeyProc(2) 

prototype  procedure  used  in XtFilePredicate(2) 

query  a  child  widget's  preferred  XtQueryGeometry(l) 

query jjeometry:  Core  method  called query_geometry(4) 

queue  XtAppNextEvent:  return  next  XtAppNextEvent(1 ) 

queue  /nondestructive^  examine XtAppPeekEvent(l) 

queue  /determine  whether  any  events XtAppPending(l) 

queue  XtNextEvent: XtNextEvent(l) 

queue  /nondestructive^  examine XtPeekEvent(l) 

queue  /determine  if  there  are  any XtPending(l) 

raw  event  handler XtRemoveRawEventHandler(l) 

read  the  multi-click  time XtGetMultiClickTime(1 ) 

read-only  GCs  XtDestroyGC:  Release XtDestroyGC(l) 

read-only,  shareable  GC XtGetGC(1) 

realize  a  widget  instance XtRealizeWidget(1 ) 

realize:  Core  method  to  set  window realize(4) 

realized  XtlsRealized: XtlsRealized(l) 

real-time  graphic  chart StripChart(5) 

receives  events  before  or  after  all/ XtlnsertRawEventHandler(l) 

receives  events  before  or  after  all/ XtlnsertEventHandler(1 ) 

recent  event  handled  by/  /retrieve XtLastTimestampProcessed(1 ) 

RectObj:  base  class  encapsulating RectObj(3) 

RectObj  widget  class  /test  whether XtlsRectObj(l) 

redirect  keyboard  input  to  a  normal XtSetKey boardFocusf  1 ) 

redirect  user  input  from  modal XtRemoveGrab(1) 

redirect  user  input  to  a  modal XtAddGrab(1) 

reference  counts  for  cached  XtAppReleaseCacheRefs(1 ) 

region  /merge  Expose XtAddExposureToRegion(l) 

register  a  case  converter XtRegisterCaseConverter(l) 

register  a  high-level  procedure  to XtSetWarningMsgHandler(l) 

register  a  key  translator XtSetKey Trans lator(1) 

register  a  new  file  as  an  input XtAppAddlnput(l) 

register  a  new  file  as  an  input XtAddlnput(l) 

register  a  new  resource  converter XtAppAddConverter(1 ) 

register  a  new  resource  converter XtAddConverter(1 ) 

register  a  procedure  to  be  called XtAppSetErrorHandler(1 ) 

register  a  procedure  to  be  called XtAppSetErrorMsgHandler(1 ) 

register  a  procedure  to  be  called XtSetErrorHandlenjI) 

register  a  procedure  to  be  called XtAppSetWamingHandler(l) 

register  a  procedure  to  be  called XtAppSetWarningMsgHandler(1 ) 

register  a  procedure  to  be  called XtSetErrorMsgHandler(l) 

register  a  procedure  to  be  called XtSetWarningHandler(l) 

register  a  procedure  to  handle XtAddEventHandler(1 ) 

register  a  type  converter  for  all XtSetTypeConverter(l) 

register  a  type  converter  in  a XtAppSetTypeConverter(1 ) 

register  a  work  procedure  for  a XtAppAddWorkProc(l) 

register  a  work  procedure  for  an XtAddWorkProc(1 ) 

register  an  action  table  with  the XtAddActions(l) 
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that/  XtlnsertRawEventHandler:   register  an  event  handler  procedure XtlnsertRawEventHandler(1 ) 

that/  XtlnsertEventHandler:   register  an  event  handler  procedure XtlnsertEventHandler(l) 

selecting/  XtAddRawEventHandler:   register  an  event  handler  without XtAddRawEventHandler(1 ) 

widget's/  XtRegisterGrabAction:   register  button  and  key  grabs  for  a XtRegisterGrabAction(1 ) 

/declare  an  action  table  and   register  it  with  the  Resource/ XtAppAddActions(l) 

/remove  a  previously   registered  event  handler XtRemoveEventHandler(1 ) 

/before  or  after  all  previously   registered  event  handlers,  without/ XtlnsertRawEventHandler(1 ) 

before  or  after  all  previously   registered  event  handlers  /events XtlnsertEventHandler(l) 

XtDispatchEvent:  dispatch   registered  handlers  for  an  event XtDispatchEvent(1 ) 

translator  /invoke  the  currently   registered  keycode-to-keysym XtTranslateKeycode(l) 

/Core  method  for  accepting  or  rejecting  the  keyboard  focus accept_focus(4) 

free  read-only  GCs  XtDestroyGC:   Release  2  compatible  function  to XtDestroyGC(l) 

/callback  function  to  release  a  cached  resource  value XtCallbackReleaseCacheRef(1 ) 

/callback  function  to  release  a  list  of  cached  values XtCallbackReleaseCacheRefList(1 ) 

ownership  /prototype  procedure  to  release  incremental  selection XtLoseSelectionlncrProc(2) 

parent/  XtUnmanageChildren:   remove  a  list  of  children  from  a XtUnmanageChildren(l) 

event/  XtRemoveEventHandler:   remove  a  previously  registered XtRemoveEventHandler(1 ) 

XtRemoveRawEventHandler:   remove  a  raw  event  handler XtRemoveRawEventHandler(1 ) 

managed  list  XtUnmanageChild:   remove  a  widget  from  its  parent's XtUnmanageChild(l) 

XtUninstallTranslations:   remove  existing  translations XtUninstallTranslations(l) 

XtCloseDisplay:  close  a  display  and   remove  it  from  an  application/ XtCloseDisplay(l) 

accelerator  table  into  its  internal   representation  /compile  an XtParseAcceleratorTable(l) 

translation  table  into  its  internal   representation  /compile  a XtParseTranslationTable(1 ) 

geometry  XtMakeGeometryRequest:   request  parent  to  change  child's XtMakeGeometryRequest(l) 

size  XtMakeResizeRequest:   request  parent  to  change  child's XtMakeResizeRequest(l) 

/prototype  procedure  called  when   requested  selection  data  arrives XtSelectionCallbackProc(2) 

method  called  when  a  child   requests  a  new  geometry  /Composite geometry_manager(4) 

XtResizeWidget:   resize  a  child  or  sibling  widget XtResizeWidget(1 ) 

core  dimensions  XtResizeWindow:   resize  a  widget  according  to  its XtResizeWindow(l) 

widget  is  resized   resize:  Core  method  called  when  a resize(4) 

XtConfigureWidget:  move  and/or  resize  widget XtConfigureWidget(l) 

Core  method  called  when  a  widget  is   resized  resize: resize(4) 

method  for  processing  constraint   resource  changes  /Constraint Constraint  set_values(4) 

Core  method  for  processing   resource  changes  set_values: set_values(4) 

result  XtDirectConvert:  perform   resource  conversion  and  cache XtDirectConvert(1 ) 

XtCallConverter:  explicitly  invoke  resource  conversions XtCallConverter(l) 

resulting  value  /look  up  and  call  a  resource  converter,  copying  the XtConvertAndStore(l) 

XtAppAddConverter:  register  a  new  resource  converter  for  an/ XtAppAddConverter(1 ) 

XtConverter:  prototype  of  a  resource  converter  procedure XtConverter(2) 

is/  /prototype  procedure  passed  as  a  resource  converter  when  XtRCallProc XtResourceDefaultProc(2) 

XtAddConverter:  register  a  new  resource  converter XtAddConverter(l) 

/prototype  procedure  for  a  new-style   resource  converter XtTypeConverter(2) 

procedure  to  destroy  cached   resource  data  /prototype XtDestructor(2) 

display  XtDatabase:  obtain  the  resource  database  for  a  particular XtDatabase(1 ) 

/set  application  variables  from   resource  database XtGetApplicationResources(1 ) 

when  XtRCallProc  is  specified  in  a  resource  list  entry  /converter XtResourceDefaultProc(2) 

particular/  /get  the  constraint  resource  list  structure  for  a XtGetConstraintResourceList(1 ) 

retrieve  default  values  for  a  resource  list  XtGetResourceList: XtGetResourceList(l) 

XtGetSubresources:  update  subpart  resource  list XtGetSubresources(l) 

from  an  ArgList  to  a  subpart  resource  list  /resource  settings XtSetSubvalues(l) 

Object:  base  class  encapsulating   resource  management  and  callbacks Object(3) 

table  and  register  it  with  the  Resource  Manager  /declare  an  action XtAppAddActk>ns(1) 

to  a  subpart/  XtSetSubvalues:  copy   resource  settings  from  an  ArgList XtSetSubvalues(1 ) 
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XtConvert:  convert  resource  type XtConvert(1 ) 

function  to  release  a  cached  resource  value  /callback XtCallbackReleaseCacheRef(1 ) 

Core  method  for  getting  subpart  resource  values  get_values_hook: get_values_hook(4) 

/specify  a  default  set  of  resource  values XtAppSetFallbackResources(1 ) 

message  during  conversion  of  string  resource  values  /issue  a  warning  XtDisplay StnngConversion Warning(  1 ) 

procedure  to  a  widget's  callback  resource  /add  a  callback Xt  AddCallback(1 ) 

/the  current  values  of  nonwidget  resources  associated  with  a  widget/ XtVaGetSubvalues(1 ) 

/retrieve  the  current  values  of  resources  associated  with  a  widget/ XtVaGetValues(l) 

/set  the  current  values  of  nonwidget  resources  associated  with  a  widget/ XtVaSetSubvalues(1 } 

/modify  the  current  values  of  resources  associated  with  a  widget/ XtVaSetValues(1 ) 

application  using  varargs/  /retrieve  resources  for  the  overall XtVaGetApplicationResources(l) 

using/  XtVaGetSubresources:  fetch  resources  for  widget  subparts XtVaGetSubresources(1 ) 

argument  list  XtGetValues:  copy  resources  from  a  widget  to  the XtGetValues(1 ) 

widget  XtSetValues:  copy  resources  from  an  ArgLJst  to  a XtSetValues(1 ) 

WMShell:  application  resources  linking  window  managers WMShell(3) 

the  reference  counts  for  cached  resources  obtained  from/  /decrement XtAppReleaseCacheRefs(1 ) 

Core  method  for  processing  subpart  resources  set_values_hook: set_values_hook(4) 

vendor-specific  shell  fields  and  resources  VendorShell: VendorShell(3) 

changejnanaged:  Composite  method  to  respond  to  a  change  in  a  list  of/ change_managed(4) 

a  resource  converter,  copying  the  resulting  value  /look  up  and  call XtConvertAndStore(1 ) 

XtBuildEventMask:  retrieve  a  widget's  event  mask XtBuildEventMask(1 ) 

resource  list  XtGetResourceLJst:  retrieve  default  values  for  a XtGetResourceList(1 ) 

XtVaGetApplicationResources:  retrieve  resources  for  the  overall/ XtVaGetApplicationResources(1 ) 

XtDisplay ToApplicationContext:  retrieve  the  application  context/ XtDisplay ToApplicationContext(1 ) 

nonwidget/  XtVaGetSubvalues:  retrieve  the  current  values  of XtVaGetSubvalues(1 ) 

resources/  XtVaGetValues:  retrieve  the  current  values  of XtVaGetValues(l) 

that  matched/  XtGetActionKeysym:  retrieve  the  keysym  and  modifiers XtGetActionKeysym(1 ) 

that/  XtGetSelectionRequest:  retrieve  the  SelectionRequest  event XtGetSelectionRequest(1 ) 

most/  XtLastTimestampProcessed:  retrieve  the  timestamp  from  the Xtl_astTimestampProcessed(1 ) 

name  of  the  specified/  XtName:  return  a  pointer  to  the  instance XtName(1 ) 

XtGetKeysymTable:  return  a  pointer  to  the/ XtGetKeysymTable(1 ) 

application's  X/  XtAppNextEvent:  return  next  event  from  an XtAppNextEvent(1 ) 

XtNextEvent:  return  next  event  from  input  queue XtNextEvent(1 ) 

XtGetApplicationNameAndClass:  return  the  application  name  and/ XtGetApplicationNameAndClass(1 ) 

nearest/  XtDisplayOfObject:  return  the  display  pointer  for  the XtDisplayOfObject(1 ) 

specified  widget  XtDisplay:  return  the  display  pointer  for  the XtDisplay (1 ) 

map  to  a/  XtKeysymToKeycodeLJst:  return  the  list  of  keycodes  that XtKeysymToKeycodeList(1 ) 

specified  widget  XtParent:  return  the  parent  widget  for  the XtParent(1 ) 

nearest  ancestor/  XtScreenOfObject:  return  the  screen  pointer  for  the XtScreenOfObject(1 ) 

specified  widget  XtScreen:  return  the  screen  pointer  for  the XtScreen(1) 

ancestor  of/  XtWindowOfObject:  return  the  window  for  the  nearest XtWindowOfObject(1 ) 

widget  XtWindow:  return  the  window  of  the  specified XtWindow(1 ) 

pair  from  widget  coordinates  to  root  coordinates  /an  x-y  coordinate XtTranslateCoords(1 ) 

/a  top-level  widget  that  is  the  root  of  a  widget  tree,  using/ XtVaAppCreateShell(1 ) 

pop  down  a  widget  from  a  callback  routine  XtCallbackPopdown: XtCallbackPopdown(1 ) 

List:  widget  for  managing  row-column  geometry LJst(5) 

XtScreenOfObject:  return  the  screen  pointer  for  the  nearest/ XtScreenOfObject(1 ) 

widget  XtScreen:  return  the  screen  pointer  for  the  specified XtScreen(1 ) 

Viewport:  scrollable  viewing  area  widget Viewport(5) 

scrolling  of  viewing  area  in/  Scrollbar:  widget  to  control Scrollbar(S) 

Scrollbar:  widget  to  control  scrolling  of  viewing  area  in/ Scrollbar(S) 

substitutions/  XtResolvePathname:  search  for  a  file  using  standard XtResolvePathname(1 ) 

substitutions  in  a/  XtFindFile:  search  for  a  file  using XtFindFile(1 ) 
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/register  an  event  handler  without 

/regstered  event  handters,  without 

;o:>:.-e  =5.  •=•:  *'*-  -ec.es'ec 

XtGetSeiectionVabes:  obtain 

XtOwnSetecton:  indicate  that 

XtDisownSelection:  indicate  that 

procedure  to  convert  incremental 

/prototype  procedure  to  convert 

/obtain  the  complete 

XtOwnSeJectionhioBmentalisetthe 

>';Cr*t-"r  '-  °rii5€    "'£"€•".=. 
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/get  the  current 

feet  te  Intnnscs 

XtSetSetectionTmeout  set  value  of 

procedure  to  cancel  momenta! 

k<v  biers  /obtanthe 
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XI  when  another  dent  claims  the 

XtGetSetectionRequest  retrieve  the 

XtfeSensitive:  check  t»  current 

XtSetSensitive:  set  the 

SmeLJne:  menu  tern 

XlGetAppfcationResourcas: 

/specify  a  default 

resources/  XtVaSetSubvalues: 

timeout  XlAppSetSelectonTimeout: 

dynamically  XtSeftluJtCickTime: 

XK)wnSelectionlnaemental: 

widget  XtSetSensifiwe: 

XtSetSetectonTimeout: 

window  realize:  Core  method  to 

riorm/  XlSetWMColormapWindows: 

XtSetSubvalues:  copy  resource 

processing  resource  changes 

negotiate  compromise  geometries 

processing  subpart  resources 

XiGetGC:  obtan  a  read-only, 

needed  XtReteaseGC:  deatocate  a 

VendorShet  vendor-specific 

AppfcatonShel:  main 

TopLeveBhet  addfenal  tofMevei 

and  create  «w  filial  appfcaton 

management  OvemdeShei:  pop-up 

managament  TranswntShet:  pop-up 

handtes  appfcafan/wtxlow  manager/ 

rsa-.e  a  x>:--: 

a  widget  is  a  subdass  of  the 

XK>eaiePopupShel:  create  a  pop-up 

HPopdown:  unmap  a  pop-up 

XiPopup:  map  a  pop-up 

XtReszeWidget  resize  a  did  or 


LfltoctriQ  for  the  event 
selecting  for  the  events 


selection  data  arrives  /prototyp 


selection  data  in  muMpte  farmate 


selection  data  s  avaiabte 


selecton  data  s  no  longer/ 
selection  data,  /prototype. 

selection  data 

&e<dcton  data . 


.  XlkisertRaw£ven*t«ler(1) 
.  XtSeiectk)nC*ackPtDC(2) 

.XK3etSelectionValues(1) 
.  XlOwnSotoction(1 ) 
.XftsownSebcfanp) 
.  XtexM*tSetedbrilrerProc(2) 


.  XlConvertSeteaionPrDc(2) 
.XtGetSeiectionValue(1) 


selection  owner  when  using/  «_ 
selection  ownership  /prototype 

selection  timeout  value 

selection  timeout  value 

selection  timeout 

selection  timeout 

selection  transfer 
selection  value  using 


c(2) 


.  XlAppGetSeteclionTroeout(1)  v 
.  XlGelSelectionTimeoul(1) 
.  XiAppSetSetedionTmeouKI) 

.XtSetSetectonT»neout(1) 

.  XiCarceConvertSeiedionPToc(2) 

.  XKietSelectionVabelncrernentaKI  ) 


setection  values  using  'HCMM 

selection  /procedure  called  by 
SetectonReqjest  event  thai/  _ 
sensitivity  state  of  a  widget  — 
sensitivity  state  of  a  widget  _ 
separator 


XiLoseSe«SonProc(2) 
XiGetSelectionRequesl(1) 


set  Ihe  current  values  of  nonwidget 

set  the  Intnnscs  selection 

se •:•>£--  :-;c«  :~6 


.XtSetSensitive(1) 
.SmeLine{5) 

.XK5etAppfcalicffleK)urces(1) 
.  XtAppSef ateckfteouces(1) 


js  -c 


.  XtVaSetSubvaluesO) 

.  XtAppSetSeiectionTineoul(1) 

.  XiSetMulliClckTme(1) 

.XK)wnSetectior*oementaH1) 

.XlSetSers*w(1) 

.  XtSetSeiectonT«T»eoul(1) 

set  wffxtow  attributes  and  create  -  reafae(4) 

set  WM_COLORMAP_WNDOWS  property  to  XtSetWMCokxinapWindows(l  ) 

setMrgs  from  an  Argbst  to  a'  -  XtSetSut*alues(1  ) 

set_vakjes:  Core  metwd  far 


set  the  sensi^  state  of  a 

set  value  of  selection  timeout 


set_vakjes_afcnost  Core  method  to 
set_vahjes_hoofc  Core  method  far 
shareable  GC 


shared  GC  when  it  s  no  longer 

re  -"eos  a--:  -eso-'ses  

sheHoranappfcation 

she!  far  an  application 


.  set_vaiues(4) 

.  set_vabes_ahnost(4) 

.  set_vabes_hook(4) 

.XlGetGC(1) 

.XAateaseGC(1) 


Shel(3) 


shel  instance  /open  a  dspiay,— 
s^'  that  bypasses  wndow  , 
shel  that  doesnl  bypass  window 
Shel:  top^evei  widget  ttat 


shel,  using  varargs  argument  styte 
Shel  widget  dass /test  whether  _ 

shel— — 

shel—- 

shel 


.TopLeveBhel(3) 
.XtAppWafee(1) 
.OvemdeSnel(3) 
.  Transien 

.  S-e,  3. 

.XiVaCreatePopupShel(l) 
.XtfeSnel(1) 
.XiCreatePopupSnel(1) 


sibfog  widget 
SirnpieMenu:  menu  cont 


»Popup(1) 

XlResizeWidg9t(1) 
SirnpieMenu^) 


X  Tooiat  Intrinsics  Reference  Manual 


/register  a  type  converter  in  a 

XtGrabKey:  passively  grab  a 

XtGrabButlon:  passively  grab  a 

/and  manage  a  child  widget  in  a 

storage  XtRealloc:  change  the 

request  parent  to  change  child's 


single  application  context XtAppSetTypeConverter(1) 

single  key  of  the  keyboard XtGrabKey(l) 

single  pointer  button XtGrabButton(l) 

single  procedure,  using  varargs/ XtVaCreateManagedWidget(t) 

size  of  an  allocated  block  of XtRealloc(l) 

size  XtMakeResizeRequest: XtMakeResizeRequest(l) 

Sme:  base  class  for  menu  entries Sme(5) 

SmeBSB:  basic  menu  entry SmeBSB(5) 

SmeLJne:  menu  item  separator SmeLJne(5) 


called  to  handle  file,  pipe,  or 

procedure,  a  pipe  procedure,  or  a 

/register  a  new  file  as  an  input 

/register  a  new  file  as  an  input 

XtPopupSpringLoaded:  map  a 

list  /search  for  a  file  using 

check  the  current  sensitivity 

XtSetSensitive:  set  the  sensitivity 

button  which  maintains  boolean 

XtHasCallbacks:  determine  the 

type  XtNew:  allocate 

XtFree:  free  an  allocated  block  of 

XtMalloc:  allocate 

the  size  of  an  allocated  block  of 

/emit  boilerplate 

widget  to  display  a  non-editable 

message  during  conversion  of 

XtNewString:  copy  an  instance  of  a 

real-time  graphic  chart 

method  to  initialize  class  part 

/get  the  constraint  resource  list 

the  byte  offset  of  a  field  within  a 

/copy  from  subpart  data 

the  byte  offset  of  a  field  within  a 

Constraint:  provides  data 

XtMergeArgLJsts:  merge  two  ArgLJst 

widget  tree,  using  varargs  argument 

internals,  using  varargs  argument 

procedure,  using  varargs  argument 

shell,  using  varargs  argument 

of  a  widget  using  varargs  argument 

application  using  varargs  argument 

subparts,  using  varargs  argument 

instance,  using  varargs  argument 

instance,  using  varargs  argument 

instance,  using  varargs  argument 

instance,  using  varargs  argument 

determine  whether  a  widget  is  a 

widget/  Aest  whether  a  widget  is  a 

class  Aest  whether  a  widget  is  a 

class  Aest  whether  a  widget  is  a 

Aest  whether  a  widget  is  a 

Aest  whether  a  widget  is  a 

widget/  Aest  whether  a  widget  is  a 


socket  input  /prototype  procedure 
socket  procedure  /unregister  a  file 
source  for  a  given  application 

source  for  an  application 

spring-loaded  pop-up  from  within  an/ 
standard  substitutions  in  a  path 
state  of  a  widget  XtlsSensitive: 
state  of  a  widget 


.  XtlnputCallbackProc(2) 

.  XtRemovelnput(l) 

.XtAppAddlnput(l) 

.XtAddlnput(l) 

.  XtPopupSpringLoaded(l) 

.  XtResotvePathname(l) 

,  XtlsSensitive(1) 

.  XtSetSensitive(1) 


state  Toggle: Toggle(5) 

status  of  a  widget's  callback  list XtHasCallbacks(1 ) 

storage  for  one  instance  of  a  data XtNew(1) 

storage XtFree(1 ) 

storage XtMalloc(1 ) 

storage  XtRealloc:  change XtRealloc(l) 

string  conversion  error  message XtStringConversionWarning(l) 

string  Label: Label(5) 

string  resource  values  /a  warning XtDisplayStringConversionWarning(1 ) 

string XtNewString(1 ) 

StripChart:  widget  to  display  a StripChart(S) 

structure  fields  /Core class_part_initialize(4) 

structure  for  a  particular  widget/ XtGetConstraintResourceLJst(1 ) 

structure  pointer  type  /determine XtOffset(1) 

structure  to  the  argument  list XtGetSubvalues(1 ) 

structure  type  /determine XtOffsetOf(1 ) 

structures  for  a  widget's  parent Constraint^) 

structures  ...,       XtMergeArgUsts(l) 


style  /widget  that  is  the  root  of  a 
style  /initialize  the  X  Toolkit  — 
style  /a  child  widget  in  a  single 
style  /create  a  pop-up 

style  /create  an  instance 

style  /resources  for  the  overall 
style  /fetch  resources  for  widget . 
style  /associated  with  a  widget ... 
style  /associated  with  a  widget ... 
style  /associated  with  a  widget ... 
style  /associated  with  a  widget 


subclass  of  a  class  XtlsSubclass:  

subclass  of  the  ApplicationShell 

subclass  of  the  Composite  widget 

subclass  of  the  Constraint  widget 

subclass  of  the  Core  widget  class 

subclass  of  the  Object  widget  class 

subclass  of  the  OverrideShell  


.XtVaAppCreateShell(l) 

.  XtVaApplnitialize(l) 

.  XtVaCreateManagedWidget(l) 

.XtVaCreatePopupShell(l) 

.XtVaCreateWidget(l) 

.  XtVaGetAppltcationResources(l) 

.  XtVaGetSubresources(l) 

.XtVaGetSubvalues(l) 

.XtVaGetValues(l) 

.XtVaSetSubvalues(l) 

.XtVaSetValues(l) 

.XtfeSubclass(l) 

.XtlsApplicationShell(l) 

.XtlsComposite(1) 

.  XtlsConstraint(l) 

.XttsWkJget(l) 

.XtfeObject(l) 

.XtteOverrideShell(l) 
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class  /test  whether  a  widget  is  a  subclass  of  the  RectObj  widget XtlsRectObj(1 ) 

/test  whether  a  widget  is  a  subclass  of  the  Shell  widget  class XtlsShell(1 ) 

widget/  /test  whether  a  widget  is  a  subclass  of  the  TopLevelShell  XtlsTopLevelShell(l) 

widget/  /test  whether  a  widget  is  a  subclass  of  the  TransientShell XtlsTransientShell(l) 

class  /test  whether  a  widget  is  a  subclass  of  the  VendorShell  widget XtlsVendorShell(1 ) 

class  /test  whether  a  widget  is  a  subclass  of  the  WMShell  widget XtlsWMShell(1 ) 

Core  method  for  initializing  subpart  data  initializejiook: initialize_hook(4) 

argument/  XtGetSubvalues:  copy  from  subpart  data  structure  to  the XtGetSubvalues(1 ) 

XtGetSubresources:  update  subpart  resource  list XtGetSubresources(1 ) 

settings  from  an  ArgLJst  to  a  subpart  resource  list  /resource XtSetSubvalues(l) 

/Core  method  for  getting  subpart  resource  values  get_values_hook(4) 

Core  method  for  processing  subpart  resources  set_values_hook: set_yalues_hook(4) 

style  /fetch  resources  for  widget  subparts,  using  varargs  argument XtVaGetSubresources(1 ) 

/search  for  a  file  using  standard  substitutions  in  a  path  list XtResolvePathname(1 ) 

XtFindFile:  search  for  a  file  using  substitutions  in  a  path XtFindFile(l) 

XtSuperclass:  obtain  a  widget's  superclass XtSuperclass(1 ) 

/for  use  with  the  XtVaNestedLJst  symbol  in  multiple  varargs  calls  XtVaCreateArgsList(l) 

XtAppAdd Actions:  declare  an  action  table  and  register  it  with  the/ XtAppAddActions(1 ) 

specification  in  the  translation  table  entry  /the  final  event XtGetActionKeysym(1 ) 

/to  the  keysy m-to-keycode  mapping  table  for  a  particular  display XtGetKeysymTable(1 ) 

/compile  an  accelerator  table  into  its  internal/ XtParseAcceleratorTaWe(1 ) 

/compile  a  translation  table  into  its  internal/ XtParseTranslationTable(l) 

/keysym  in  the  keyboard  mapping  table  maintained  by  the  Intrinsics XtKeysymToKeycodeLJst(1 ) 

XtAddActions:  register  an  action  table  with  the  Translation  Manager XtAddActions(l) 

in  the  widget's  translation  table  /to  the  event  bindings XtRegisterGrabAction(l) 

widget  Template:  widget  to  create  a  custom  Template(5) 

of  the/  XtlsApplicationShell:  test  whether  a  widget  is  a  subclass XtlsApplicationShell(1 ) 

of  the  Composite/  XtlsComposite:  test  whether  a  widget  is  a  subclass XtlsComposite(1 ) 

of  the  Constraint/  XtlsConstraint:  test  whether  a  widget  is  a  subclass XtlsConstraint(1 ) 

of  the  Core  widget/  Xtls Widget:  test  whether  a  widget  is  a  subclass XtlsWidget(1 ) 

of  the  Object  widget/  XtlsObject:  test  whether  a  widget  is  a  subclass XtlsObject(1 ) 

of  the/  XtlsOvem'deShell:  test  whether  a  widget  is  a  subclass XtlsOverrideSheR(1 ) 

of  the  RectObj  widget/  XtlsRectObj:  test  whether  a  widget  is  a  subclass XtlsRectObj(1 ) 

of  the  Shell  widget/  XtlsShell:  test  whether  a  widget  is  a  subclass XtlsShell(1 ) 

of  the/  XtlsTopLevelShell:  test  whether  a  widget  is  a  subclass XtlsTopLevelShell(1 ) 

of  the/  XtlsTransientSheil :  test  whether  a  widget  is  a  subclass XtlsTransientShell(1 ) 

of  the/  Xtls  VendorShell:  test  whether  a  widget  is  a  subclass Xtls  VendorShell(1 ) 

of  the  WMShell  widget/  Xtls  WMShell:  test  whether  a  widget  is  a  subclass XtlsWMShell(1 ) 

/obtain  the  error  database  text  for  an  error  or  a  warning XtAppGetErrorDatabaseText(1 ) 

/obtain  the  error  database  text  for  an  error  or  a  warning XtGetErrorDatabaseText(1 ) 

Text:  text-editing  widget Text(5) 

Text:  text-editing  widget Text(5) 

/set  the  multi-click  time  dynamically XtSetMultiClickTime(l) 

read  the  multi-click  time  XtGetMultiClickTime: XtGetMultiClickTime(l) 

XtRemoveTimeOut:  unregister  a  timeout  procedure XtRemoveTimeOut(l) 

XtAddTimeOut:  create  a  timeout  value XtAddTimeOut(1 ) 

/get  the  current  selection  timeout  value XtAppGetSelectionTimeout(1 ) 

/get  the  current  selection  timeout  value XtGetSelectionTimeout(1 ) 

a  procedure  after  a  specified  timeout  XtAppAddTimeOut:  invoke XtAppAddTimeOut(l) 

set  the  Intrinsics  selection  timeout  XtAppSetSelectionTimeout: XtAppSetSelectionTimeout(1 ) 

set  value  of  selection  timeout  XtSetSelectionTimeout: XtSetSelectionTimeout(1 ) 

callback  procedure  invoked  when  timeouts  expire  /prototype XtTimerCallbackProc(2) 

event  handled  by/  /retrieve  the  timestamp  from  the  most  recent XtLastTimestampProcessed(l) 
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by  XtDispatchEvent  that  contains  a  timestamp  /recent  event  handled XtLastTimestampProcessed(l) 

boolean  state  Toggle:  button  which  maintains Toggle(5) 

Xtlnitialize:  initialize  toolkit  and  display Xtlnitialize(l) 

XtApplnitialize:  initialize  the  X  Toolkit  internals,  create  an/ XtApplnitialize(1 ) 

XtVaApplnitialize:  initialize  the  X  Toolkit  internals,  using  varargs/ XtVaApplnitialize(1 ) 

/initialize  the  X  Toolkit  internals XtToolkitlnitialize(l) 

TopLevelShell:  additional  top-level  shell  for  an  application TopLevelShell(3) 

application/window  manager/  Shell:  top-level  widget  that  handles Shell(3) 

of  a/  XtVaAppCreateShell:  create  a  top-level  widget  that  is  the  root XtVaAppCreateShell(1 ) 

XtAppCreateShell:  create  additional  top-level  widget XtAppCreateShell(l) 

/create  an  additional   top-level  widget XtCreateApplicationShell(1 ) 

shell  for  an  application  TopLevelShell:  additional  top-level TopLevelShell(3) 

a  widget  is  a  subclass  of  the  TopLevelShell  widget  class  /whether XtlsTopLevelShell(l) 

procedure  called  after  a  data  transfer  completes  /prototype XtSelectionDoneProc(2) 

to  cancel  incremental  selection  transfer  /prototype  procedure XtCancelConvertSelectionProc(2) 

indicate  completion  of  incremental  transfer  /prototype  procedure  to XtSelectionDonelncrProc(2) 

selection  value  using  incremental  transfers  /obtain  the XtGetSelectionValuelncremental(1 ) 

selection  values  using  incremental  transfers  /obtain  multiple XtGetSelectionValueslncremental(1 ) 

owner  when  using  incremental   transfers  /set  the  selection XtOwnSelectionlncremental(1 ) 

doesn't  bypass  window  management  TransientShell:  pop-up  shell  that TransientShell(3) 

/a  widget  is  a  subclass  of  the  TransientShell  widget  class  XtlsTransientShell(1 ) 

XtKeyProc:  prototype  procedure  to  translate  a  key XtKeyProc(2) 

instance  XtNameToWidget:  translate  a  widget  name  to  a  widget XtNameToWidget(1 ) 

pointer  into  a/  XtWindowToWidget:   translate  a  window  and  display XtWindowToWidget(1 ) 

from  widget/  XtTranslateCoords:  translate  an  x-y  coordinate  pair XtTranslateCoords(1 ) 

register  an  action  table  with  the  Translation  Manager  XtAddActions: XtAddActions(l) 

final  event  specification  in  the  translation  table  entry  /the XtGetActionKeysym(l) 

XtParseTranslationTable:  compile  a  translation  table  into  its  internal/ XtParseTranslationTable(l) 

the  event  bindings  in  the  widget's   translation  table  /according  to XtRegisterGrabAction(l) 

XtOverrideTranslations:  merge  new  translations,  overwriting  widget's/ XtOverrideTranslations(1 ) 

ones  /nondestructive^  merge  new   translations  with  widget's  existing XtAugmentTranslations(l) 

/remove  existing  translations XtUninstallTranslations(1 ) 

XtSetKeyTranslator:  register  a  key  translator XtSetKeyTranslator(1 ) 

the  default  keycode-to-keysym   translator  XtTranslateKey : XtTranslateKey(1 ) 

registered  keycode-to-keysym   translator  /invoke  the  currently XtTranslateKeycode(l) 

/widget  that  is  the  root  of  a  widget  tree,  using  varargs  argument  style XtVaAppCreateShell(1 ) 

Ahe  SelectionRequest  event  that  triggered  the  convert_selection/ XtGetSelectionRequest(l) 

XtSetTypeConverter:  register  a  type  converter  for  all  application/ XtSetTypeConverter(1 ) 

XtAppSetTypeConverter:  register  a  type  converter  in  a  single/ XtAppSetTypeConverter(1 ) 

XtConvert:  convert  resource  type XtConvert(l) 

storage  for  one  instance  of  a  data  type  XtNew:  allocate XtNew(1) 

a  field  within  a  structure  pointer  type  /determine  the  byte  offset  of XtOffset(1) 

of  a  field  within  a  structure  type  /determine  the  byte  offset XtOffsetOf(1 ) 

XtPopdown:   unmap  a  pop-up  shell XtPopdown(1 ) 

XtUnmapWidget:   unmap  a  widget  explicitly Xtl)nmapWidget(1 ) 

procedure,  or  a/  XtRemovelnput:   unregister  a  file  procedure,  a  pipe XtRemovelnput(l) 

XtRemoveTimeOut:   unregister  a  timeout  procedure XtRemoveTimeOut(1 ) 

XtRemoveWorkProc:   unregister  a  work  procedure XtRemoveWorkProc(1 ) 

XtRemoveActionHook:   unregister  an  action  hook  procedure XtRemoveActionHook(1 ) 

XtGetSubresources:   update  subpart  resource  list XtGetSubresources(l) 

of  a/  XtConvertCase:  determine  upper-case  and  lower-case  versions XtConvertCase(l) 

to  normal/  XtRemoveGrab:  redirect  user  input  from  modal  widget  back XtRemoveGrab(1) 

XtAddGrab:  redirect   user  input  to  a  modal  widget XtAddGrab(1 ) 


Permuted  Index  51 


XtSetMappedWhenManaged:  change  the  value  of  a  widget's/ XtSetMappedWhenManaged(1 ) 

XtSetSelectionTimeout:  set  value  of  selection  timeout XtSetSelectionTimeout(l) 

/obtain  the  selection  value  using  incremental  transfers XtGetSelectionValuelncremental(l) 

XtAddTimeOut:  create  a  timeout  value XtAddTimeOut(l) 

get  the  current  selection  timeout  value  XtAppGetSelectionTimeout: XtAppGetSelectionTimeout(l) 

to  release  a  cached  resource  value  /callback  function XtCallbackReleaseCacheRef(1 ) 

converter,  copying  the  resulting  value  /look  up  and  call  a  resource XtConvertAndStore(l) 

get  the  current  selection  timeout  value  XtGetSelectionTimeout: XtGetSelectionTimeout(l) 

XtGetResourceList:  retrieve  default  values  for  a  resource  list XtGetResourceList(l) 

method  for  getting  subpart  resource  values  get_values_hook:  Core get_values_hook(4) 

associated/  /retrieve  the  current  values  of  nonwidget  resources XtVaGetSubvalues(t) 

XtVaSetSubvalues:  set  the  current  values  of  nonwidget  resources/ XtVaSetSubvalues(1 ) 

XtVaGetValues:  retrieve  the  current  values  of  resources  associated  with/ XtVaGetValues(l) 

XtVaSetValues:  modify  the  current  values  of  resources  associated  with/ XtVaSetValues(l) 

/obtain  multiple  selection  values  using  incremental  transfers XtGetSelectionValueslncremental(l) 

specify  a  default  set  of  resource  values  XtAppSetFallbackResources: XtAppSetFallbackResources(l) 

to  release  a  list  of  cached  values  /callback  function XtCallbackReleaseCacheReflJst(1 ) 

conversion  of  string  resource  values  /a  warning  message  during XtDisplayStringConversionWarning(l) 

is  the  root  of  a  widget  tree,  using  varargs  argument  style  /widget  that XtVaAppCreateShell(1 ) 

the  X  Toolkit  internals,  using  varargs  argument  style  /initialize XtVaApplnitialize(l) 

widget  in  a  single  procedure,  using  varargs  argument  style  /a  child XtVaCreateManagedWidget(1 ) 

/create  a  pop-up  shell,  using  varargs  argument  style XtVaCreatePopupShell(l) 

an  instance  of  a  widget  using  varargs  argument  style  /create XtVaCreateWidget(l) 

for  the  overall  application  using  varargs  argument  style  /resources XtVaGetApplicationResources(l) 

for  widget  subparts,  using  varargs  argument  style  /resources  XtVaGetSubresources(1 ) 

with  a  widget  instance,  using  varargs  argument  style  /associated XtVaGetSubvalues(1 ) 

with  a  widget  instance,  using  varargs  argument  style  /associated XtVaGetValues(l) 

with  a  widget  instance,  using  varargs  argument  style  /associated XtVaSetSubvalues(l) 

with  a  widget  instance,  using  varargs  argument  style  /associated XtVaSetValues(1 ) 

XtVaNestedList  symbol  in  multiple  varargs  calls  /for  use  with  the XtVaCreateArgsList(l) 

/dynamically  allocate  a  varargs  list  for  use  with  the/ XtVaCreateArgsList(l) 

/set  application  variables  from  resource  database XtGetApplicationResources(1 ) 

method  for  initializing  instance  variables  initialize:  Core initialize^) 

fields  and  resources  VendorShell:  vendor-specific  shell VendorShell(3) 

a  widget  is  a  subclass  of  the  VendorShell  widget  class  /whether XtlsVendorShell(1 ) 

resources  VendorShell:  vendor-specific  shell  fields  and VendorShell(3) 

XtCheckSubclass:  in  DEBUG  mode,  verify  an  object's  class XtCheckSubclass(l) 

/determine  upper-case  and  lower-case  versions  of  a  keysym XtConvertCase(l) 

Paned:  geometry-managing  widget  for  vertical  or  horizontal Paned(5) 

/widget  to  control  scrolling  of  viewing  area  in  another  widget Scrollbar(5) 

Viewport:  scrollable  viewing  area  widget VTewport(5) 

widget  Viewport:  scrollable  viewing  area Viewport(5) 

call  the  installed  high-level  warning  handler  XtAppWamingMsg: XtAppWamingMsg(l) 

call  the  installed  low-level  warning  handler  XtWaming: XtWaming(1) 

call  the  installed  high-level  warning  handler  XtWamingMsg: XtWamingMsg(1 ) 

prototype  for  low-level  error  and  warning  handlers  XtErrorHandler: XtErrorHandler(2) 

/prototype  for  high-level  error  and  warning  handlers XtErrorMsgHandler(2) 

of  string  resource  values  /issue  a  warning  message  during  conversion XtDisplayStringConversionWaming(l) 

database  text  for  an  error  or  a  warning  /obtain  the  error XtAppGetErrorDatabaseText(l) 

database  text  for  an  error  or  a  warning  /obtain  the  error XtGetErrorDatabaseText(1 ) 

XtResizeWindow:  resize  a  widget  according  to  its  core/ XtResizeWindow(1 ) 

/install  all  accelerators  from  a  widget  and  its  descendants  onto  a/ XtlnstallAIIAccelerators(1 ) 

the  windows  associated  with  a  widget  and  its  descendants  /destroy XtUnrealizeWidget(1 ) 
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/redirect  user  input  from  modal  widget  back  to  normal  destination XtRemoveGrab(1) 

Box:  geometry-managing  box  widget Box(5) 

widgets  /initialize  a  widget  class  without  creating  any XtlnitializeWidgetClass(1 ) 

list  structure  for  a  particular  widget  class  /constraint  resource XtGetConstraintResourceList(1 ) 

a  subclass  of  the  ApplicationShell  widget  class  /whether  a  widget  is XtlsApplicationShell(1 ) 

is  a  subclass  of  the  Composite  widget  class  /test  whether  a  widget XtlsCom posite(1 ) 

is  a  subclass  of  the  Constraint  widget  class  Aest  whether  a  widget XtlsConstraint(1 ) 

widget  is  a  subclass  of  the  Object  widget  class  /test  whether  a XtlsObject(t) 

is  a  subclass  of  the  OverrideShell  widget  class  /test  whether  a  widget XtlsOverrideShell(1 ) 

widget  is  a  subclass  of  the  RectObj  widget  class  Aest  whether  a XtlsRectObj(1 ) 

a  widget  is  a  subclass  of  the  Shell  widget  class  Aest  whether XtlsShell(1 ) 

is  a  subclass  of  the  TopLevelShell  widget  class  Aest  whether  a  widget XtlsTopLevelShell(1 ) 

is  a  subclass  of  the  TransientShell  widget  class  Aest  whether  a  widget XtlsTransientShell(1 ) 

is  a  subclass  of  the  VendorShell   widget  class  Aest  whether  a  widget XllsVendorShell(1 ) 

a  widget  is  a  subclass  of  the  Core  widget  class  Aest  whether XtlsWidget(l) 

widget  is  a  subclass  of  the  WMShell  widget  class  Aest  whether  a XtlsWMShell(1 ) 

/an  x-y  coordinate  pair  from  widget  coordinates  to  root/ XtTranslateCoords(1 ) 

Core:  fundamental  widget Core(3) 

Dialog:  dialog  box   widget Dialog (5) 

XtUnmapWidget:  unmap  a  widget  explicitly XtUnmapWidget(1 ) 

geometry  List:  widget  for  managing  row-column List(5) 

XtParent:  return  the  parent  widget  for  the  specified  widget XtParent(1) 

Paned:  geometry-managing  widget  for  vertical  or  horizontal Paned(5) 

XtCallbackPopdown:  pop  down  a  widget  from  a  callback  routine XtCallbackPopdown(l) 

list  XtUnmanageChild:  remove  a  widget  from  its  parent's  managed XtUnmanageChild(l) 

XtlsRealized:  determine  whether  a  widget  has  been  realized XtlsRealized(l) 

a  window  and  display  pointer  into  a  widget  ID  Aranslate XtWindowToWidget(l) 

children  Form:  geometry-managing   widget  implementing  constraints  on  Form(5) 

varargs/  /create  and  manage  a  child  widget  in  a  single  procedure,  using XtVaCreateManagedWidget(1 ) 

/resources  associated  with  a  widget  instance,  using  varargs/ XtVaGetSubvalues(1 ) 

/of  resources  associated  with  a  widget  instance,  using  varargs/ XtVaGetValues(l) 

/resources  associated  with  a  widget  instance,  using  varargs/ XtVaSetSubvalues(1 ) 

/of  resources  associated  with  a  widget  instance,  using  varargs/ XtVaSetValues(l) 

XtDestroyWidget:  destroy  a  widget  instance XtDestroyWidget(l) 

translate  a  widget  name  to  a  widget  instance  XtNameToWidget: XtNameToWidget(l) 

XtRealizeWidget:  realize  a  widget  instance XtRealizeWidget(l) 

XtlsSubclass:  determine  whether  a  widget  is  a  subclass  of  a  class XtlsSubclass(1 ) 

ApplicationShell/  Aest  whether  a  widget  is  a  subclass  of  the XtlsApplicationShell(l) 

XtlsComposite:  test  whether  a  widget  is  a  subclass  of  the/ XtlsCom posite(1 ) 

XtlsConstraint:  test  whether  a  widget  is  a  subclass  of  the/ XtlsConstraint(1 ) 

widget/  XtlsWidget:  test  whether  a  widget  is  a  subclass  of  the  Core XtlsWidget(1 ) 

widget/  XtlsObject:  test  whether  a  widget  is  a  subclass  of  the  Object XtlsObject(1 ) 

XtlsOverrideShell:  test  whether  a  widget  is  a  subclass  of  the/ XtlsOverrideShell(1 ) 

widget/  XtlsRectObj:  test  whether  a  widget  is  a  subclass  of  the  RectObj XtlsRectObj(1 ) 

widget/  XtlsShell:  test  whether  a  widget  is  a  subclass  of  the  Shell XtlsShell(1 ) 

XtlsTopLevelShell:  test  whether  a  widget  is  a  subclass  of  the/ XtlsTopLevelShell(1 ) 

XtlsTransientShell:  test  whether  a  widget  is  a  subclass  of  the/ XtlsTransientShellf  1 ) 

Xtls VendorShell:  test  whether  a  widget  is  a  subclass  of  the/ Xtls VendorShell(  1 ) 

widget/  XtlsWMShell:  test  whether  a  widget  is  a  subclass  of  the  WMShell XtlsWMShell(l) 

destroy:  Core  method  called  when  a  widget  is  destroyed destroy(4) 

/Core  method  called  when  a  widget  is  destroyed query_geometry(4) 

XtlsManaged:  determine  whether  a  widget  is  managed  by  its  parent XtlsManaged(1 ) 

resize:  Core  method  called  when  a  widget  is  resized resize(4) 
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XtNameToWidget:  translate  a  widget  name  to  a  widget  instance XtNameToWidget(l) 

XtMoveWidget:  move  a  widget  on  the  display XtMoveWidget(l) 

of  viewing  area  in  another  widget  /widget  to  control  scrolling Scrollbar(S) 

SimpleMenu:  menu  container  widget SimpleMenu(5) 

argument  style  /fetch  resources  for  widget  subparts,  using  varargs XtVaGetSubresources(1 ) 

Template:  widget  to  create  a  custom  widget Template(5) 

Text:  text-editing  widget Text(5) 

Shell:  top-level  widget  that  handles/ Shell(3) 

tree,  using/  /create  a  top-level  widget  that  is  the  root  of  a  widget XtVaAppCreateShell(1 ) 

viewing  area  in  another/  Scrollbar:  widget  to  control  scrolling  of Scrollbar(5) 

Template:  widget  to  create  a  custom  widget Template(5) 

string  Label:  widget  to  display  a  non-editable Label(5) 

graphic  chart  StripChart:  widget  to  display  a  real-time StripChart(5) 

XtMapWidget:  map  a  widget  to  its  display XtMapWidget(1 ) 

managed/  XtManageChild:  add  a  widget  to  its  parent's  list  of XtManageChild(l) 

XtGetValues:  copy  resources  from  a  widget  to  the  argument  list XtGetValues(l) 

style  /widget  that  is  the  root  of  a  widget  tree,  using  varargs  argument XtVaAppCreateShell(1 ) 

/create  an  instance  of  a  widget  using  varargs  argument  style XtVaCreateWidget(l) 

Viewport:  scrollable  viewing  area  widget Viewport(5) 

redirect  user  input  to  a  modal  widget  XtAddGrab: XtAddGrab(1) 

create  additional  top-level  widget  XtAppCreateShell: XtAppCreateShell(1 ) 

callback  function  to  pop  up  a  widget  XtCallbackExclusive: XtCallbackExclusive(1 ) 

callback  function  to  pop  up  a  widget  XtCallbackNone: XtCallbackNone(1 ) 

callback  function  to  pop  up  a  widget.  XtCallbackNonexclusive: XtCallbackNonexclusive(l) 

move  and/or  resize  widget  XtConfigureWidget: XtConfigureWidget(1 ) 

create  an  additional  top-level  widget  XtCreateApplicationShell: XtCreateApplicationShell(1 ) 

create  and  manage  a  child  widget  XtCreateManagedWidget: XtCreateManagedWidget(1 ) 

create  an  instance  of  a  widget  XtCreateWidget: XtCreateWidget(l) 

display  pointer  for  the  specified  widget  XtDisplay:  return  the XtDisplay(l) 

ancestor  of  object  that  is  of  class  Widget  /pointer  for  the  nearest XtDisplayOfObject(1 ) 

a  widget's  accelerators  on  another  widget  /install XtlnstallAccelerators(1 ) 

the  current  sensitivity  state  of  a  widget  XtlsSensitive:  check XtlsSensitive(1 ) 

built-in  action  for  popping  down  a  widget  XtMenuPopdown: XtMenuPopdown(1 ) 

built-in  action  for  popping  up  a  widget  XtMenuPopup: XtMenuPopup(1 ) 

the  parent  widget  for  the  specified  widget  XtParent:  return XtParent(1) 

resize  a  child  or  sibling  widget  XtResizeWidget: XtResizeWidget(1 ) 

screen  pointer  for  the  specified  widget  XtScreen:  return  the XtScreen(1 ) 

ancestor  of  object  that  is  of  class  Widget  /pointer  for  the  nearest XtScreenOfObject(l) 

to  a  normal  descendant  of  a  child  widget  /redirect  keyboard  input XtSetKeyboardFocus(1 ) 

set  the  sensitivity  state  of  a  widget  XtSetSensitive: XtSetSensitive(1 ) 

copy  resources  from  an  ArgList  to  a  widget  XtSetValues: XtSetValues(1 ) 

the  application  context  for  a  given  widget  /get XtWidgetToApplicationContext(1 ) 

return  the  window  of  the  specified  widget  XtWindow: XtWindow(1) 

ancestor  of  object  that  is  of  class  Widget  /the  window  for  the  nearest XtWindowOfObject(1 ) 

XtlnstallAccelerators:  install  a  widget's  accelerators  on  another/ XtlnstallAccelerators(1 ) 

XtCallAcceptFocus:  call  a  widget's  acceptjocus  procedure XtCallAcceptFocus(l) 

of  callback  procedures  to  a  given  widget's  callback  list  /add  a  list XtAddCallbacks(1 ) 

/execute  the  procedures  in  a  widget's  callback  list XtCallCallbacks(l) 

/determine  the  status  of  a  widget's  callback  list XtHasCallbacks(l) 

/add  a  callback  procedure  to  a  widget's  callback  resource XtAddCallback(l) 

to  a  change  in  a  list  of  managed  widgets  /method  to  respond change_managed(4) 

XtClass:  obtain  a  widget's  class XtClass(1) 

XtBuildEventMask:  retrieve  a  widget's  event  mask XtBuildEventMask(1 ) 
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/merge  new  translations  with  widget's  existing  ones XtAugmentTranslations(l) 

/merge  new  translations,  overwriting  widget's  existing  ones XtOverrideTranslations(l) 

attachment  point  for  dragging  other  widgets  Grip: Grip(5) 

a  list  of  children  from  a  parent  widget's  managed  list  /remove XtUnmanageChildren(1 ) 

/change  the  value  of  a  widget's  map_when_managed  field XtSetMappedWhenManaged(1 ) 

provides  data  structures  for  a  widget's  parent  Constraint: Constraint(3) 

XtQueryGeometry :  query  a  child  widget's  preferred  geometry XtQueryGeometry(1 ) 

XtSuperclass:  obtain  a  widget's  superclass XtSuperclass(1 ) 

managed/  XtManageChildren:  add  widgets  to  their  parent's  list  of XtManageChildren(1 ) 

Ao  the  event  bindings  in  the  widget's  translation  table XtRegisterGrabAction(l) 

/register  button  and  key  grabs  for  a  widget's  window  according  to  the/ XtRegisterGrabAction(1 ) 

XtCreateWindow:  create  widget's  working  window XtCreateWindow(1 ) 

a  widget  class  without  creating  any  widgets  /initialize XtlnitializeWidgetClass(1 ) 

/button  and  key  grabs  for  a  widget's  window  according  to  the  event/ XtRegisterGrabAction(1 ) 

XtWindowToWidget:  translate  a  window  and  display  pointer  into  a/ XtWindowToWidget(1 ) 

realize:  Core  method  to  set  window  attributes  and  create  window realized) 

XtWindowOfObject:  return  the  window  for  the  nearest  ancestor  of/ XtWindowOfObject(1 ) 

pop-up  shell  that  bypasses  window  management  OverrideShell: OverrideShell(3) 

pop-up  shell  that  doesn't  bypass  window  management  TransientShell: TransientShell(3) 

/property  to  inform  window  manager  of  custom  colormaps  XtSetWMColormapWindows(1 ) 

application  resources  linking  window  managers  WMShell: WMShell(S) 

XtWindow:  return  the  window  of  the  specified  widget XtWindow(1 ) 

to  set  window  attributes  and  create  window  realize:  Core  method realize(4) 

create  widget's  working  window  XtCreateWindow: XtCreateWindow(1 ) 

and/  XtUnrealizeWidget:  destroy  the  windows  associated  with  a  widget XtUnrealizeWidget(1 ) 

inform/  XtSetWMColormapWindows:  set  WM_COLORMAP_WINDOWS  property  to  ....  XtSetWMColormapWindows(l) 

linking  window  managers  WMShell:  application  resources WMShell(S) 

a  widget  is  a  subclass  of  the  WMShell  widget  class  /test  whether XtlsWMShell(1 ) 

XtAppAddWorkProc:  register  a  work  procedure  for  a  given/ XtAppAddWorkProc(1 ) 

XtAddWorkProc:  register  a  work  procedure  for  an  application  XtAddWorkProc(1 ) 

XtRemoveWorkProc:  unregister  a  work  procedure XtRemoveWorkProc(1 ) 

XtCreateWindow:  create  widget's  working  window XtCreateWindow(1 ) 

next  event  from  an  application's  X  event  queue  /return XtApoNextEvent(1 ) 

XtAoplnitialize:  initialize  the  X  Toolkit  internals,  create  an/ XtApplnitialize(1 ) 

XtVaApplnitialize:  initialize  the  X  Toolkit  internals,  using  varargs/ XtVaApplnitialize(l) 

XtToolkitlnitialize:  initialize  the  X  Toolkit  internals XtToolkitlnitialize(1 ) 

/prototype  procedure  called  by  Xt  when  another  client  claims  the/ XtLoseSelectionProc(2) 

hook  procedure.  XtActionHookProc:  prototype  action XtActionHookProc(2) 

procedure  XtActionProc:  prototype  action XtActionProc(2) 

table  with  the  Translation  Manager  XtAddActions:  register  an  action XtAddActions(1 ) 

procedure  to  a  widget's  callback/  XtAddCallback:  add  a  callback Xt AddCallback(1 ) 

callback  procedures  to  a  given/  XtAddCallbacks:  add  a  list  of XtAddCallbacks(l) 

resource  converter  XtAddConverter:  register  a  new XtAddConverter(1 ) 

procedure  to  handle  events  XtAddEventHandler:  register  a XtAddEventHandler(1 ) 

and  GraphicsExpose  events  into  a/  XtAddExposureToRegion:  merge  Expose XtAddExposureToRegion(1 ) 

modal  widget  Xt AddGrab:  redirect  user  input  to  a XtAddGrab(1 ) 

an  input  source  for  an  application  XtAdd Input :  register  a  new  file  as XtAddlnput(1 ) 

event  handler  without  selecting/  XtAddRawEventHandler:  register  an XtAddRawEventHandler(1 ) 

value  XtAddTimeOut:  create  a  timeout XtAddTimeOut(1 ) 

procedure  for  an  application  XtAddWorkProc:  register  a  work XtAdd WorkProc(1 ) 

hook  XtAppAddActionHook:  add  an  action XtAppAddActionHook(l) 

table  and  register  it  with  the/  XtAppAdd Actions:  declare  an  action XtAppAdd Actions (1 ) 

resource  converter  for  an/  XtAppAddConverter:  register  a  new XtAppAddConverter(1 ) 
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as  an  input  source  for  a  given/  XtAppAdd Input :  register  a  new  file XtAppAddlnput(1 ) 

after  a  specified  timeout  XtAppAddTimeOut:  invoke  a  procedure XtAppAddTimeOut(1 ) 

procedure  for  a  given  application  XtAppAddWorkProc:  register  a  work XtAppAdd WorkProc(1 ) 

top-level  widget  XtAppCreateShell:  create  additional XtAppCreateShell(1 ) 

fatal  error  procedure  XtAppError:  call  the  installed XtAppError(l) 

fatal  error  handler  XtAppErrorMsg:  call  the  high-level XtAppErrorMsg(l) 

error  database  XtAppGetErrorDatabase:  obtain  the XtAppGetErrorDatabase(l) 

the  error  database  text  for  an/  XtAppGetErrorOatabaseText:  obtain XtAppGetErrorDatabaseText(1 ) 

current  selection  timeout  value  XtAppGetSelectionTimeout:  get  the XtAppGetSelectionTimeout(1 ) 

Toolkit  internals,  create  an/  XtApplnitialize:  initialize  the  X XtApplnitialize(1 ) 

given  application  XtAppMainLoop:  process  input  from  a XtAppMainLoop(1 ) 

from  an  application's  X  event/  XtAppNextEvent:  return  next  event XtAppNextEvent(1 ) 

examine  the  head  of  an/  XtAppPeekEvent:  nondestructive^ XtAppPeekEvent(l) 

events  are  in  an  application's/  XtAppPending:  determine  whether  any XtAppPending(1 ) 

input  event  XtAppProcessEvent:  process  one XtAppProcessEvent(l) 

decrement  the  reference  counts  for/  XtAppReleaseCacheRefs:  explicitly XtAppReleaseCacheRefs(1 ) 

procedure  to  be  called  on  fatal/  XtAppSetErrorHandler:  register  a XtAppSetErrorHandler(1 ) 

procedure  to  be  called  on  fatal/  XtAppSetErrorMsgHandler:  register  a XtAppSetErrorMsgHandler(l) 

a  default  set  of  resource  values  XtAppSetFallbackResources:  specify XtAppSetFallbackResources(1 ) 

Intnnsics  selection  timeout  XtAppSetSelectionTimeout:  set  the XtAppSetSelectionTimeout(1 ) 

type  converter  in  a  single/  XtAppSetTypeConverter:  register  a XtAppSetTy peConverter(1 ) 

procedure  to  be  called  on  nonfatal/  XtAppSetWamingHandler:  register  a XtAppSetWamingHandler(1 ) 

a  procedure  to  be  called  on/  XtAppSetWamingMsgHandler:  register XtAppSetWarningMsgHandler(l) 

nonfatal  error  procedure  XtAppWaming:  call  the  installed XtAppWaming(l) 

high-level  warning  handler  XtAppWamingMsg:  call  the  installed XtAppWarningMsg(l) 

nondestructive^  merge  new/  XtAugmentTranslations: XtAugmentTranslations(1 ) 

widget's  event  mask  XtBuildEventMask:  retrieve  a XtBuildEventMask(l) 

acceptjocus  procedure  XtCallAcceptFocus:  call  a  widget's XtCallAcceptFocus(1 ) 

procedure  without  generating/  XtCallActionProc:  invoke  an  action XtCall ActionProc(1 } 

function  to  pop  up  a  widget  XtCallbackExclusive:  callback XtCallbackExclusive(1 ) 

to  pop  up  a  widget  XtCallbackNone:  callback  function XtCallbackNone(1 ) 

function  to  pop  up  a  widget.  XtCallbackNonexclusive:  callback XtCallbackNonexcfusive(1 ) 

widget  from  a  callback  routine  XtCallbackPopdown:  pop  down  a XtCallbackPopdown(1 ) 

procedure  XtCallbackProc:  prototype  callback XtCallbackProc(2) 

function  to  release  a  cached/  XtCallbackReleaseCacheRef:  callback XtCallbackReleaseCacheRef(l) 

callback  function  to  release  a/  XtCallbackReleaseCacheRefList: XtCallbackReleaseCacheRefList(1 ) 

procedures  in  a  callback  list,/  XtCallCallbackList:  execute  the XtCallCallbackLJst(1 ) 

procedures  in  a  widget's  callback/  XtCallCallbacks:  execute  the XtCallCall backs (1 ) 

resource  conversions  XtCallConverter:  explicitly  invoke XtCallConverter(l) 

for  cached  resources  obtained  from  XtCallConverter  /reference  counts  . — XtAppReleaseCacheRefs(1 ) 

initialize  elements  to  zero  XtCalloc:  allocate  an  array  and XtCalloc(1) 

prototype  procedure  to  cancel/  XtCancelConvertSelectionProc: XtCancelConvertSelectionProc(2) 

called  to  convert  the  case  of/  XtCaseProc:  prototype  procedure XtCaseProc(2) 

verify  an  object's  class  XtCheckSubclass:  in  DEBUG  mode XtCheckSubclass(1 ) 

XtClass:  obtain  a  widget's  class XtClass(1) 

remove  it  from  an  application/  XtCloseDisplay:  close  a  display  and XtCloseDisplay(1 ) 

resize  widget  XtConfigureWidget:  move  and/or XtConfigureWidget(l) 

XtConvert:  convert  resource  type XtConvert(l) 

a  resource  converter,  copying  the/  XtConvertAndStore:  look  up  and  call XtConvertAndStore(1 ) 

procedure  for  argument  conversion.  XtConvertArgProc:  prototype XtConvertArgProc(2) 

and  lower-case  versions  of  a/  XtConvertCase:  determine  upper-case XtConvertCase(l) 

resource  converter  procedure  XtConverter:  prototype  of  a XtConverter(2) 

prototype  procedure  to  convert/  XtConvertSelectionlncrProc: XtConvertSelectionlncrProc(2) 
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procedure  to  convert  selection/  XtConvertSelectionProc:  prototype XtConvertSelectionProc(2) 

an  application  context  XtCreateApplicationContext:  create XtCreateApplicationContext(1 ) 

additional  top-level  widget  XtCreateApplicationShell:  create  an XtCreateApplicationShell(1 ) 

manage  a  child  widget  XtCreateManagedWidget:  create  and XtCreateManagedWidget(1 ) 

shell  XtCreatePopupShell:  create  a  pop-up XtCreatePopupShell(1 ) 

of  a  widget  XtCreateWidget:  create  an  instance XtCreateWidget(1 ) 

working  window  XtCreateWindow:  create  widget's XtCreateWindow(l) 

database  for  a  particular  display  XtDatabase:  obtain  the  resource XtDatabase(1 ) 

destroy  an  application  context  and/  XtDestroy AppiicationContext : XtDestroy ApplicationContext(  1 ) 

function  to  free  read-only  GCs  XtDestroyGC:  Release  2  compatible XtDestroyGC(l) 

instance  XtDestroy  Widget:  destroy  a  widget XtDestroy  Widget(1 ) 

to  destroy  cached  resource  data  XtDestructor:  prototype  procedure XtDestructor(2) 

conversion  and  cache  result  XtDirectConvert:  perform  resource XtDirectConvert(l) 

selection  data  is  no  longer/  XtDisownSelection:  indicate  that XtDisownSelection(l) 

registered  handlers  for  an  event  XtDispatchEvent:  dispatch XtDispatchEvent(l) 

/the  most  recent  event  handled  by  XtDispatchEvent  that  contains  a/ XtLastTimestampProcessed(1 ) 

pointer  for  the  specified  widget  XtDisplay :  return  the  display XtDisplay (1 ) 

/name  and  class  as  passed  to  XtDisplay  Initialize  for  a/ XtGetAppiicationNameAndClass(1 ) 

display  and  add  it  to  an/  XtDisplay  Initialize:  initialize  a XtDisplay  Initialize(i) 

display  pointer  for  the  nearest/  XtDispJayOfObject:  return  the XtDisp)ayOfObject(l) 

issue  a  warning  message  during/  XtDisplayStringConversionWaming: XtDisplayStringConversionWarning(1 ) 

retrieve  the  application  context/  XtDisplay ToApplicationContext: XtDisplay ToApplicationContext(1 ) 

error  handler  XtError:  call  the  low-level  fatal XtError(1) 

low-level  error  and  warning/  XtErrorHandler:  prototype  for XtErrorHandler(2) 

fatal  error  handler  XtErrorMsg:  call  the  high-level XtErrorMsg(l) 

high-level  error  and  warning/  XtErrorMsgHandler:  prototype  for XtErrorMsgHandler(2) 

handler  procedure.  XtEventHandler:  prototype  event XtEventHandler(2) 

procedure  used  in  filename/  XtFilePredicate:  prototype XtFilePredicate(2) 

substitutions  in  a  path  XtFindFile:  search  for  a  file  using XtFindFile(1 ) 

storage  XtFree:  free  an  allocated  block  of XtFree(1 ) 

keysym  and  modifiers  that  matched/  XtGetActionKeysym:  retrieve  the XtGetActionKeysym(l) 

return  the  application  name  and/  XtGetApplicationNameAndClass: XtGetApplicationNameAndClass(1 ) 

application  variables  from/  XtGetApplicationResources:  set XtGetApplicationResources(1 ) 

the  constraint  resource  list/  XtGetConstraintResourceLJst:  get XtGetConstraintResourceLJst(1 ) 

error  database  XtGetErrorDatabase:  obtain  the XtGetErrorDatabase(1 ) 

error  database  text  for  an  error/  XtGetErrorOatabaseText:  obtain  the XtGetErrorDatabaseText(1 ) 

shareable  GC  XtGetGC:  obtain  a  read-only XtGetGC(1 ) 

to  the  keysy m-to-keycode  mapping/  XtGetKeysymTable:  return  a  pointer XtGetKeysymTable(1 ) 

multi-click  time  XtGetMultiClickTime:  read  the XtGetMultiClickTime(1 ) 

values  for  a  resource  list  XtGetResourceLJst:  retrieve  default XtGetResourceLJst(1 ) 

SelectionRequest  event  that/  XtGetSelectionRequest:  retrieve  the XtGetSelectionRequest(1 ) 

current  selection  timeout  value  XtGetSelectionTimeout:  get  the XtGetSelectionTimeout(1 ) 

complete  selection  data  XtGetSelection Value:  obtain  the XtGetSelection Value(1 ) 

obtain  the  selection  value  using/  XtGetSelection Valuelncremental: XtGetSelectionValuelncremental(1 ) 

selection  data  in  multiple  formats  XtGetSelection  Values:  obtain XtGetSelectionValues(1 ) 

obtain  multiple  selection  values/  XtGetSelectionValueslncremental: XtGetSelectionValueslncremental(1 ) 

resource  list.  XtGetSubresources:  update  subpart XtGetSubresources(l) 

data  structure  to  the  argument/  XtGetSubvalues:  copy  from  subpart XtGetSubvalues(1 } 

widget  to  the  argument  list  XtGetValues:  copy  resources  from  a XtGetValues(l) 

single  pointer  button  XtGrabButton:  passively  grab  a XtGrabButton(1 ) 

key  of  the  keyboard  XtGrabKey :  passively  grab  a  single XtGrabKey  (1 ) 

keyboard  XtGrabKey  board:  actively  grab  the XtGrabKeyboard(1 ) 

pointer  XtGrabPointer:  actively  grab  the XtGrabPointer(l) 
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status  of  a  widget's  callback  list  XtHasCallbacks:  determine  the XtHasCallbacks(1 ) 

and  display  /(Initialize:  initialize  toolkit Xtlnitialize(l) 

a  widget  class  without  creating/  XtlnitializeWidgetClass:  initialize XtlnitializeWidgetClass(1 } 

procedure  called  to  handle  file,/  XtlnputCallbackProc:  prototype XtlnputCallbackProc(2) 

event  handler  procedure  that/  XtlnsertEventHandler:  register  an XtlnsertEventHandler(1 ) 

an  event  handler  procedure  that/  XtlnsertRawEventHandler:  register XtlnsertRawEventHandler(1 ) 

widget's  accelerators  on  another/  XtlnstallAccelerators:  install  a XtlnstallAccelerators(1 ) 

all  accelerators  from  a  widget  and/  Xt  Install  All  Accelerators:  install Xt  Install  All  Accelerators(  1 ) 

a  widget  is  a  subclass  of  the/  XtlsApplicationShell:  test  whether XtlsApplicationShell(1 ) 

widget  is  a  subclass  of  the/  XtlsCom posite:  test  whether  a XtlsComposite(1 ) 

widget  is  a  subclass  of  the/  XtlsConstraint:  test  whether  a XtlsConstraint(1 ) 

widget  is  managed  by  its  parent  XtlsManaged:  determine  whether  a XtlsManaged(l) 

is  a  subclass  of  the  Object  widget/  XtlsObject:  test  whether  a  widget XtlsObject(l) 

widget  is  a  subclass  of  the/  XtlsOverrideShell:  test  whether  a XtlsOverrideShell(1 ) 

widget  has  been  realized  XtlsRealized:  determine  whether  a XtlsRealized(1 ) 

is  a  subclass  of  the  RectObj/  XtlsRectObj:  test  whether  a  widget XtlsRectObj(1 ) 

sensitivity  state  of  a  widget  XtlsSensitive:  check  the  current XtlsSensitive(l) 

a  subclass  of  the  Shell  widget/  XtlsShell:  test  whether  a  widget  is XtlsShell(1 ) 

widget  is  a  subclass  of  a  class  XtlsSubclass:  determine  whether  a XtlsSubclass(1 ) 

widget  is  a  subclass  of  the/  XtlsTopLevelShell:  test  whether  a XtlsTopLevelShell(1 ) 

widget  is  a  subclass  of  the/  XtlsTransientShell:  test  whether  a XtlsTransientShell(1 ) 

widget  is  a  subclass  of  the/  XtlsVendorShell:  test  whether  a XtlsVendorShell(1 ) 

is  a  subclass  of  the  Core  widget/  XtlsWidget:  test  whether  a  widget XtlsWidget(1 ) 

is  a  subclass  of  the  WMShell/  Xtls  WMShell :  test  whether  a  widget Xt  Is  WMShell(1 ) 

translate  a  key  XtKeyProc:  prototype  procedure  to XtKeyProc(2) 

list  of  keycodes  that  map  to  a/  XtKeysymToKeycodeList:  return  the XtKeysymToKeycodeList(1 ) 

the  timestamp  from  the  most  recent/  XtLastTimestampProcessed:  retrieve XtLastTimestampProcessed(1 ) 

procedure  to  release  incremental/  XtLoseSelectionlncrProc:  prototype XtLoseSelectionlncrProc(2) 

procedure  called  by  Xt  when/  XtLoseSelectionProc:  prototype XtLoseSelectionProc(2) 

events  XtMainLoop:  continuously  process XtMainLoop(1 ) 

parent  to  change  child's  geometry  XtMakeGeometry  Request:  request XtMakeGeometryRequest(1 ) 

to  change  child's  size  XtMakeResizeRequest:  request  parent XtMakeResizeRequest(l) 

XtMalloc:  allocate  storage XtMalloc(1) 

parent's  list  of  managed  children  XtManageChild:  add  a  widget  to  its XtManageChild(1 ) 

their  parent's  list  of  managed/  XtManageChildren:  add  widgets  to XtManageChildren(l) 

display  XtMapWidget :  map  a  widget  to  its XtMapWidget(1 ) 

popping  down  a  widget  XtMenuPopdown:  built-in  action  for XtMenuPopdown(1 ) 

popping  up  a  widget  XtMenuPopup:  built-in  action  for XtMenuPopup(1 ) 

structures  XtMergeArgLJsts:  merge  two  ArgList XtMergeArgUsts(1 ) 

display  XtMoveWidget:  move  a  widget  on  the XtMoveWidget(1 ) 

instance  name  of  the  specified/  XtName:  return  a  pointer  to  the XtName(1 ) 

name  to  a  widget  instance  XtNameToWidget:  translate  a  widget XtNameToWidget(1 ) 

instance  of  a  data  type  XtNew:  allocate  storage  for  one XtNew(1 ) 

string  XtNewString:  copy  an  instance  of  a XtNewString(1 ) 

input  queue  XtNextEvent:  return  next  event  from XtNextEvent(l) 

elements  in  a  fixed-size  array  XtNumber:  determine  the  number  of XtNumber(1 ) 

of  a  field  within  a  structure/  XtOffset:  determine  the  byte  offset XtOffset(1 ) 

offset  of  a  field  within  a/  XtOffsetOf:  determine  the  byte XtOffsetOf(l) 

and  add  a  display  to  an/  XtOpen Display:  open,  initialize XtOpenDisplay(l) 

determine  position  for  new  child  XtOrderProc:  Composite  function  to XtOrderProc(2) 

translations,  overwriting  widget's/  XtOverrideTranslations:  merge  new XtOverrideTranslations(l) 

selection  data  is  available  XtOwnSelection:  indicate  that XtOwnSelection(1 ) 

selection  owner  when  using/  XtOwnSelection  Incremental:  set  the XtOwnSelectionlncremental(1 ) 
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for  the  specified  widget  XtParent:  return  the  parent  widget XtParent(1 ) 

accelerator  table  into  its/  XtParseAcceleratorTable:  compile  an XtParseAcceleratorTable(1 ) 

translation  table  into  its/  XtParseTranslationTable:  compile  a XtParseTranslationTable(1 ) 

examine  the  head  of  an/  XtPeekEvent:  nondestructive^ XtPeekEvent(1 ) 

any  events  in  an  application's/  XtPending:  determine  if  there  are XtPending(1 ) 

XtPopdown:  unmap  a  pop-up  shell XtPopdown(l) 

XtPopup:  map  a  pop-up  shell XtPopup(1) 

spring-loaded  pop-up  from  within/  XtPopupSpringLoaded:  map  a XtPopupSpringLoaded(1 ) 

event  XtProcessEvent:  process  one  input XtProcessEvent(1 ) 

widget's  preferred  geometry   XtQueryGeometry:  query  a  child XtQueryGeometry(l) 

/passed  as  a  resource  converter  when  XtRCallProc  is  specified  in  a/ XtResourceDefaultProc(2) 

instance  XtRealizeWidget:  realize  a  widget XtRealizeWidget(1 ) 

allocated  block  of  storage  XtRealloc:  change  the  size  of  an XtRealloc(1 ) 

case  converter  XtRegisterCaseConverter:  register  a XtRegisterCaseConverter(1 ) 

button  and  key  grabs  for  a/  XtRegisterGrabAction:  register XtRegisterGrabAction(1 ) 

when  it  is  no  longer  needed   XtReleaseGC:  deallocate  a  shared  GC XtReleaseGC(l) 

action  hook  procedure  XtRemoveActionHook:  unregister  an XtRemoveActionHook(1 ) 

procedures  from  a  callback  list  XtRemoveAIICallbacks:  delete  all XtRemoveAIICallbacks(1 ) 

procedure  from  a  callback  list  XtRemoveCallback:  delete  a XtRemoveCallback(1 ) 

procedures  from  a  callback  list  XtRemoveCallbacks:  delete  a  list  of XtRemoveCallbacks(1 ) 

previously  registered  event/  XtRemoveEventHandler:  remove  a XtRemoveEventHandler(1 ) 

from  modal  widget  back  to  normal/  XtRemoveGrab:  redirect  user  input XtRemoveGrab(1 ) 

procedure,  a  pipe  procedure,  or  a/  XtRemovelnput:  unregister  a  file XtRemovelnput(1 ) 

raw  event  handler  XtRemoveRawEventHandler:  remove  a XtRemoveRawEventHandler(1 ) 

timeout  procedure  XtRemoveTimeOut:  unregister  a XtRemoveTimeOut(1 ) 

procedure  XtRemoveWorkProc:  unregister  a  work XtRemoveWorkProc(1 ) 

sibling  widget  XtResizeWidget:  resize  a  child  or XtResizeWidget(1 ) 

according  to  its  core  dimensions   XtResizeWindow:  resize  a  widget XtResizeWindow(1 ) 

file  using  standard  substitutions/  XtResolvePathname:  search  for  a XtResolvePathname(1 ) 

procedure  passed  as  a  resource/  XtResourceDefaultProc:  prototype XtResourceDefaultProc(2) 

for  the  specified  widget  XtScreen:  return  the  screen  pointer XtScreen(1 ) 

pointer  for  the  nearest  ancestor/  XtScreenOfObject:  return  the  screen XtScreenOfObject(1 ) 

procedure  called  when  requested/  XtSelectionCallbackProc:  prototype XtSelectionCallbackProc(2) 

procedure  to  indicate  completion/  XtSelectionDonelncrProc:  prototype XtSelectionDonelncrProc(2) 

procedure  called  after  a  data/  XtSelectionDoneProc:  prototype XtSelectionDoneProc(2) 

dynamically   XtSetArg:  modify  an  argument  list XtSetArg(1) 

procedure  to  be  called  on  fatal/  XtSetErrorHandler:  register  a XtSetErrorHandler(l) 

procedure  to  be  called  on  nonfatal/  XtSetErrorMsgHandler:  register  a XtSetErrorMsgHandler(1 ) 

keyboard  input  to  a  normal/  XtSetKeyboardFocus:  redirect XtSetKeyboardFocus(1 ) 

translator  XtSetKeyTranslator:  register  a  key XtSetKeyTranslator(1 ) 

value  of  a  widget's/  XtSetMappedWhenManaged:  change  the XtSetMapoedWhenManaged(1 ) 

multi-click  time  dynamically   XtSetMultiClickTime:  set  the XtSetMultiClickTime(1 ) 

selection  timeout  XtSetSelectionTimeout:  set  value  of XtSetSelectionTimeout(1 ) 

state  of  a  widget  XtSetSensitive:  set  the  sensitivity XtSetSensitive(1 ) 

settings  from  an  ArgLJst  to  a/  XtSetSubvalues:  copy  resource XtSetSubvalues(1 ) 

converter  for  all  application/  XtSetTypeConverter:  register  a  type XtSetTypeConverter(1 ) 

ArgList  to  a  widget  XtSetValues:  copy  resources  from  an XtSetValues(1 ) 

procedure  to  be  called  on  nonfatal/  XtSetWamingHandter:  register  a XtSetWamingHandler(l) 

high-level  procedure  to  be  called/  XtSetWamingMsgHandler:  register  a XtSetWamingMsgHandler(1 ) 

WM_COLORMAP_WINDOWS  property  to/  XtSetWMCotormapWindows:  set XtSetWMColormapWindows(l) 

boilerplate  string  conversion/  XtStringConversionWaming:  emit XtStringConversionWarning(1 ) 

superclass   XtSuperclass:  obtain  a  widget's XtSuperclass(l) 

callback  procedure  invoked  when/  XtTimerCallbackProc:  prototype XtTimerCallbackProc(2) 


Permuted  Index 


X  Toolkit  internals  XtTodkitlnitialize:  initialize  the XtToolkitlnitialize(1) 

coordinate  pair  from  widget/  XtTranslateCoords:  translate  an  x-y XtTranslateCoords(1 ) 

keycode-to-keysym  translator  XtTranslateKey:  the  default XtTranslateKey(l) 

currently  registered/  XtTranslateKeycode:  invoke  the XtTranslateKeycode(1 ) 

procedure  for  a  new-style  resource/  XtTypeConverter:  prototype XtTypeConverter(2) 

button  grab  XtUngrabButton:  cancel  a  passive XtUngrabButton(1 ) 

grab  XtUngrabKey:  cancel  a  passive  key XtUngrabKey(1 ) 

keyboard  grab  XtUngrabKey  board:  cancel  an  active XtUngrabKeyboard(l) 

pointer  grab  XtUngrabPointer:  cancel  an  active XtUngrabPointer(1 ) 

existing  translations  XtUnmstallTranslations:  remove XtUninstallTranslations(1 ) 

from  its  parent's  managed  list  XtUnmanageChild:  remove  a  widget XtUnmanageChild(l) 

of  children  from  a  parent  widget's/  XtUnmanageChildren:  remove  a  list XtUnmanageChildren(1 ) 

explicitly  XtUnmapWidget:  unmap  a  widget XtUnmapWidget(1 ) 

windows  associated  with  a  widget/  XtUnrealizeWidget:  destroy  the XtUnrealizeWidget(l) 

top-level  widget  that  is  the  root/  XtVaAppCreateShell:  create  a XtVaAppCreateShell(l) 

Toolkit  internals,  using  varargs/  XtVaApplnitialize:  initialize  the  X XtVaApplnitialize(1) 

allocate  a  varargs  list  for  use/  XtVaCreateArgsLJst:  dynamically XtVaCreateArgsLJst(l) 

manage  a  child  widget  in  a  single/  XtVaCreateManagedWidget:  create  and  XtVaCreateManagedWidget(1 ) 

pop-up  shell,  using  varargs/  XtVaCreatePopupShell:  create  a XtVaCreatePopupShell(1 ) 

instance  of  a  widget  using  varargs/  XtVaCreate Widget:  create  an  XtVaCreateWidget(l) 

retneve  resources  for  the  overall/  XtVaGetApplicationResources: XtVaGetApplicationResources(1 ) 

resources  for  widget  subparts,/  XtVaGetSubresources:  fetch XtVaGetSubresources(1 ) 

current  values  of  nonwidget/  XtVaGetSubvalues:  retrieve  the XtVaGetSubvalues(l) 

values  of  resources  associated/  XtVaGet Values:  retneve  the  current XtVaGetValues(1 } 

/a  varargs  list  for  use  with  the  XtVaNestedUst  symbol  in  multiple/ XtVaCreateArgsList(l) 

values  of  nonwidget  resources/  XtVaSetSubvalues:  set  the  current XtVaSetSubvalues(1 ) 

values  of  resources  associated/  XtVaSet Values:  modify  the  current XtVaSetValues(l) 

tow-level  warning  handler  XtWaming:  call  the  installed XtWaming(1 } 

high-level  warning  handler  XtWamingMsg:  call  the  installed XtWamingMsg(1 ) 

the  application  context  for  a/  XtWidgetToApplicationContext:  get XtWidgetToApplicationContext(1 } 

specified  widget  XtWindow:  return  the  window  of  the XtWindow(1 ) 

foe  the  nearest  ancestor  of  object/  XtWindowOfObject:  return  the  window XtWindowOfOb)ect(l) 

window  and  display  pointer  into  a/  XtWindowToWidget:  translate  a XtWmdowToWidget(1 ) 

performing  background  processing  XtWofkProc:  prototype  procedure  for XtWorkProc(2) 

XtTranslateCoords:  translate  an  x-y  coordinate  pair  from  widget/ XtTranslateCoords(l) 

an  array  and  initialize  elements  to  zero  XtCalloc:  allocate XtCaltoc(1) 
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Section  1 


Intrinsics  Functions  and  Macros 


This  section  contains  alphabetically-organized  reference  pages  for  each 
Intrinsics  function  and  macro.  Each  page  contains  a  synopsis  of  the  rou 
tine's  calling  sequence  and  arguments,  a  description  of  its  function,  a 
description  of  any  structures  or  data  types  used  by  the  function,  and  a  refer 
ence  to  related  routines. 


In  This  Section: 


XtAddActions 

XtAddCallback 

XtAddCallbacks 

XtAddConverter 

XtAddEventHandler 

XtAddExposureToRegion 

XtAddGrab 

XtAddlnput 

XtAddRawEventHandler 

XtAddTimeOut 

XtAddWorkProc 

XtAppAddActionHook 

XtAppAddActions 

XtAppAddConverter 

XtAppAdd  Input 

XtAppAddTimeOut 

XtAppAddWbrkProc 

XtAppCreateShell 

XtAppError 

XtAppErrorMsg 

XtAppGetErrorDatabase 

XtAppGetErrorDatabaseText 

XtAppGetSelectionTimeout 

XtApplnitialize 

XtAppMalnLoop 

XtAppNextEvent 


XtAppPeekEvent 

XtAppPending 

XtAppProcessEvent 

XtAppReleaseCacheRefs 

XtAppSetErrorHandler 

XtAppSetErrorMsgHandler 

XtAppSetFallbackResources 

XtAppSetSelectionTimeout 

XtAppSetTypeConverter 

XtAppSetWarningHandler 

XtAppSetWarningMsgHandler 

XtAppWarning 

XtAppWarningMsg 

XtAugmentTranslations 

XtBuildEventMask 

XtCallAcceptFocus 

XtCailActionProc 

XtCallbackExclusive 

XtCallbackNone 

XtCallbackNonexclusive 

XtCallbackPopdown 

XtCallbackReleaseCacheRef 

XtCallbackReleaseCacheRefList 

XtCallCallbackList 

XtCallCallbacks 

XtCallConverter 


XtCalloc 

XtCheckSubclass 

XtClass 

XtCloseDisplay 

XtConfigureWidget 

XtConvert 

XtConvertAndStore 

XtConvertCase 

XtCreateApplicationContext 

XtCreateApplicationShell 

XtCreateManagedWidget 

XtCreatePopupShell 

XtCreateWidget 

XtCreate  Window 

XtDatabase 

XtDestroyApplicationContext 

XtDestroyGC 

XtDestroyWidget 

XtDireclConvert 

XtDisownSelection 

XtOispatchEvent 

XtOisplay 

XtDisplay  Initialize 

XtDisplayOfObject 

XtOisplayStringConversionWarning 

XtDisplay  ToApplicationContext 


XtError 

XtErrorMsg 

XtFindFile 

XtFree 

XtGetActionKeysym 

XtGetApplicationNameAndClass 

XtGetApplicationResources 

XtGetConstraintResourceList 

XtG  etE  rror  Database 

XtGetErrorDatabaseText 

XtGetGC 

XtGetKeysymTable 

XtGetMultiClickTime 

XtGetResourceList 

XtGetSelectionRequest 

XtGetSelectionTimeout 

XtGetSelectionValue 

XtG  etSelection  Val  ue  Incremental 

XtGetSelectionValues 

XtGetSelectionValues  Incremental 

XtGetSubresources 

XtGetSubvalues 

XtGetValues 

XtGrabButton 

XtGrabKey 

XtG  rabKey  board 

XtGrabPointer 

XtHasCallbacks 

Xtlnitialize 

XtlnitializeWidgetClass 

XtlnsertEventHandler 

XtlnsertRawEventHandler 

XtlnstallAccelerators 

XtlnstallAIIAccelerators 

XtlsApplicationShell 

XtlsComposite 

XtlsConstraint 

XtlsManaged 

XtlsObject 

XtlsOverrideShell 

XtlsRealized 

XtlsRectObj 

XtlsSensitive 

XtlsShell 

XtlsSubclass 

XtlsTopLevelShell 

XtlsTransientShell 

XtlsVendorShell 

XtlsWidget 

XtlsWMShell 

XtKeysymToKeycodeList 

XtLastTimestampProcessed 

XtMainLoop 

XtMakeGeometry  Request 

XtMakeResizeRequest 

XtMafloc 

XtManageChild 


XtManageChildren 

XtMapWidget 

XtMenuPopdown 

XtMenu Popup 

XtMergeArg  Lists 

XtMoveWidget 

XtName 

XtNameToWidget 

XtNew 

XtNewString 

XtNextEvent 

XtNumber 

XtOffset 

XtOffsetOf 

XtOpenDisplay 

XtOverrideTranslations 

XtOwnSelection 

XtOwnSelectionlncremental 

XtParent 

XtParseAcceleratorTable 

XtParseTranslationTable 

XtPeekEvent 

XtPending 

XtPopdown 

XtPopup 

XtPopupSpringLoaded 

XtProcessEvent 

XtQueryGeometry 

XtRealizeWidget 

XtRealloc 

XtRegisterCaseConverter 

XtRegisterGrabAction 

XtReleaseGC 

XtRemoveActionHook 

XtRemoveAIICallbacks 

XtRemoveCallback 

XtRemoveCallbacks 

XtRemoveEventHandler 

XtRemoveGrab 

XtRemovelnput 

XtRemoveRawEventHandler 

XtRemoveTimeOut 

XtRemoveWorkProc 

XtResizeWidget 

XtResizeWindow 

XtResolvePathname 

XtScreen 

XtScreenOfObject 

XtSetArg 

XtSetErrorHandler 

XtSetErrorMsgHandler 

XtSetKeyboardFocus 

XtSetKeyTranslator 

XtSetMappedWhenManaged 

XtSetMultiClickTime 

XtSetSelectionTimeout 

XtSetSensitive 


XtSetSubvalues 

XtSetTypeConverter 

XtSetValues 

XtSetWarningHandler 

XtSetWarningMsgHandler 

XtSetWMColormapWindows 

XtStringConversion  Warning 

XtSuperclass 

XtToolkitlnitialize 

XtTranslateCoords 

XtTranslateKey 

XtTrans  lateKey  code 

XtUngrabButton 

XtUngrabKey 

XtUngrabKeyboard 

XtUngrabPointer 

XtUninstallTranslations 

XtUnmanageChild 

XtUnmanageChildren 

XtUnmapWidget 

XtUnrealizeWidget 

XtVaAppCreateShell 

XtVaApplnitialize 

XtVaCreateArgsList 

XtVaCreateManagedWidget 

XtVaCreatePopupShell 

XtVaCreateWidget 

XtVaGetApplicationResources 

XtVaGetSubresources 

XtVaGetSubvalues 

XtVaGetValues 

XtVaSetSubvalues 

XtVaSetValues 

XtWarning 

XtWarningMsg 

XtWidgetToApplicationContext 

XtWindow 

XtWindowOfObject 

XtWindowToWidget 


XtAddActions 

— Xt  -  Translations  and  Actions- 
Name 

XtAddActions  —  register  an  action  table  with  the  Translation  Manager. 

Synopsis 

void  XtAddActions  (actions,  nu/n_actions) 
XtActionList  actions; 
Cardinal  num_actions; 

Arguments 

actions  Specifies  the  action  table  to  register. 

num_acti  ons      Specifies  the  number  of  entries  in  this  action  table. 
Description 

XtAddActions  has  been  superseded  by  XtAppAddActions.  Using  XtAddActions,  an 
application  can  register  its  own  action  tables  with  the  Translation  Manager.  An  action  table 
consists  of  a  list  of  string  names  (which  can  be  used  in  translation  tables  to  associate  an  action 
with  one  or  more  events)  and  corresponding  function  pointers.  The  function  pointer  is  of  type 

XtActionProc. 

By  convention,  the  string  and  the  function  name  are  identical  except  that  the  function  name 
begins  with  an  upper-case  letter,  as  in  the  example: 

static   XtActionsRec   two_quits [ ]    =    { 
{"confirm",    Confirm}, 
{"quit",    Quit}, 

This  mapping  from  strings  to  function  pointers  is  necessary  to  allow  translation  tables  to  be 
specified  in  resource  files,  which  are  made  up  entirely  of  strings. 

For  example,  the  Command  widget  has  procedures  to  take  the  following  actions: 

Set  the  appearance  of  the  Command  widget  to  indicate  it  is  activated  when  a  pointer  but 
ton  has  been  pressed  in  it. 

•         Unset  the  button  back  to  its  normal  mode. 

Highlight  the  button  borders  when  the  pointer  enters  the  Command  widget. 
Unhighlight  the  button  borders  when  the  pointer  leaves. 
Notify  any  callbacks  that  the  button  has  been  activated. 

The  action  table  for  the  Command  widget  class  makes  these  functions  available  to  translation 
tables  written  for  Command  or  any  subclass: 

XtActionsRec  actionTable [ ]  =  { 
{"Set",  Set}, 
{"Unset",        Unset}, 
{"Highlight",    Highlight}, 
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Xt  Add  Actions  (continued)  Xt  -  Translations  and  Actions 

{"Unhighlight",     Unhighlight} 
{"Notify",  Notify}, 


The  Intrinsics  reserve  all  action  names  and  parameters  starting  with  the  characters  Xt  for  future 
standard  enhancements.  Users,  applications  and  widgets  should  not  declare  action  names  or 
pass  parameters  starting  with  these  characters  except  to  invoke  specified  built-in  Intrinsics 
functions. 

The  actions  specified  in  a  translation  can  be  registered  before  or  after  the  translation  table  is 
parsed. 

The  items  in  an  action  list  registered  with  xtAddActions  are  registered  globally  for  the 
entire  application.  By  contrast,  the  action  list  specified  in  a  widget  class  structure  is 
local  —  only  translations  specified  by  the  widget  itself  can  access  local  actions.  However,  a 
widget's  local  translation  can  access  global  actions,  if  there  is  no  local  action  of  the  same  name. 

Action  procedures  should  not  assume  that  the  widget  in  which  they  are  invoked  is  realized;  an 
accelerator  specification  can  cause  an  action  procedure  to  be  called  for  a  widget  which  does  not 
yet  have  a  window.  Widget  writers  should  also  note  which  of  a  widget's  callback  lists  are 
invoked  from  action  procedures  and  should  warn  clients  not  to  assume  the  widget  is  realized  in 
those  callbacks. 

If  an  application  registers  more  than  one  global  action  with  the  same  name,  the  most  recently 
registered  action  is  used.  The  Intrinsics  register  an  action  table  for  xtMenuPopup  and  xt- 

MenuPopdown  as  part  of  XtCreateApplicationContext. 

The  Core  class  structure  holds  a  list  of  translations  and  actions.  Chapter  7,  Events,  Transla 
tions,  and  Accelerators,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming,  Manual,  contains 
general  discussion  and  examples. 

Structures 

The  XtActionList  is  a  pointer  to  an  XtActionsRec,  defined  as  follows  in  <X1  I/Intrin 
sic.  h>: 

typedef  _XtActionsRec  *XtActionList; 

typedef   struct   _XtActionsRec    { 

String   string; 

XtActionProc   proc; 
}    XtActionsRec; 

The  string  field  is  the  name  that  you  use  in  translation  tables  to  access  the  procedure.  The 
proc  field  is  a  pointer  to  a  procedure  that  implements  the  functionality. 

The  form  of  an  XtActionProc  is  described  in  XtActionProc  (2). 

See  Also 

XtAppAddActions(\\  XtParseTranslationTable(\\  MenuPopdown(l),  MenuPopup(l), 

XtActionProc  (2), 

CoreQ). 
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—  Xt- Callbacks- 


f  XtAddCallback 


Name 

XtAddCallback  —  add  a  callback  procedure  to  a  widget's  callback  resource. 

Synopsis 

void  XtAddCallback  (object,  cal  lback_name,  callback,  client_data) 
Widget  object; 
String  callback_name; 
XtCallbackProc  callback; 
XtPointer  client_data; 

Arguments 

object  Specifies  the  object;  may  be  of  class  Object  or  any  subclass  thereof. 

cailbac^_name  Specifies  the  resource  name  of  the  callback  list  to  which  the  procedure  is  to 
be  appended.  SeextCallbackProc(2). 

Specifies  the  callback  procedure  to  be  added. 


client_data      Specifies  the  argument  to  be  passed  to  the  specified  callback  procedure  when 
it  is  invoked  by  XtCallCallbacks,  or  specifies  NULL. 

Description 

Generally  speaking,  a  widget  expecting  to  interact  with  an  application  will  declare  one  or  more 
callback  lists  as  resources;  the  application  adds  functions  to  these  callback  lists,  which  will  be 
invoked  whenever  the  predefined  callback  conditions  are  met  Callback  lists  are  resources,  so 
that  the  application  can  set  or  change  the  function  that  will  be  invoked. 

Callbacks  are  not  necessarily  invoked  in  response  to  any  event;  a  widget  can  call  the  specified 
routines  at  any  arbitrary  point  in  its  code,  whenever  it  wants  to  provide  a  "hook"  for  application 
interaction.  For  example,  all  widgets  provide  an  xtNdestroyCallback  resource  to  allow 
applications  to  interpose  a  routine  to  be  executed  when  the  widget  is  destroyed. 

Widgets  can  define  additional  callback  lists  as  they  see  fit.  For  example,  the  Athena  Command 
widget  defines  the  XtNcallback  callback  list  to  notify  clients  when  the  widget  has  been 
activated  (by  the  user  clicking  on  it  with  the  pointer).  (This  is  actually  a  poor  choice  of  names. 
It  should  have  been  given  a  more  specific  name,  such  as  XtNnotif  yCallback.) 

Callback  functions  are  registered  with  a  widget  using  a  call  to  XtAddCallback  or  xtAdd- 
Callbacks.  Even  though  callback  lists  are  resources,  callback  functions  cannot  be  added 
from  resource  files,  since  callback  lists  are  maintained  in  a  private  internal  form  by  the  Intrin- 
sics.  They  cannot  be  modified  directly  except  through  one  of  the  calls  (such  as  XtAdd 
Callback)  provided  to  access  them. 

XtAddCallback  adds  a  new  callback  to  the  end  of  the  callback  list.  A  callback  will  be 
invoked  as  many  times  as  it  occurs  in  the  callback  list.  See  xtCallbackProc(2)  for  a 
description  of  the  format  of  a  callback  function. 

Use  xtAddCallbacks  to  add  a  list  of  callbacks  to  a  widget's  callback  list. 

Callbacks  differ  from  actions  in  the  way  that  the  registered  function  is  invoked.  For  callbacks, 
the  trigger  is  an  abstract  occurrence  defined  by  the  widget,  which  may  or  may  not  be 
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event-related.  The  routines  on  a  widget's  callback  lists  are  invoked  by  the  widget  code,  using  a 
call  to  xtCallCallbacks.  Actions,  on  the  other  hand,  are  invoked  directly  by  Xt,  as  the 
result  of  an  event  combination  specified  by  the  translations  mechanism. 

Another  major  difference  between  an  action  function  and  a  callback  function  is  that  action 
functions  are  called  with  an  event  as  an  argument,  while  actions  do  not  have  the 
client_data  or  call_data  arguments  present  for  callback  functions.  This  means  the 
only  way  to  pass  application  data  into  an  action  function  is  through  global  variables.  On  the 
other  hand,  the  presence  of  the  event  argument  means  that  you  can  use  the  contents  of  the  event 
structure  in  the  action  function. 

See  Also 

XtAddCollbacks(\\  XtCallCallbacks  (I),  XtRemoveAllCallbacks(\),  XtRemoveCallback(\),  XtRemove- 

Callbacks(l), 

XtCalIbackProc(2). 
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— Xt- Callbacks- 


f  XtAddCallbacks 


Name 

XtAddCallbacks  —  add  a  list  of  callback  procedures  to  a  given  widget's  callback  list. 

Synopsis 

void  XtAddCallbacks (object,  callback_name,  callbacks) 
Widget  object; 
String  callback_name; 
XtCallbackList  callbacks; 

Arguments 

object  Specifies  the  object;  may  be  of  class  Object  or  any  subclass  thereof. 

caJ lback_name  Specifies  the  resource  name  of  the  callback  list  to  which  the  procedure  is  to 
be  appended. 

callbacks          Specifies  the  NULL-terminated  list  of  callback  procedures  and  corresponding 
client  data. 

Description 

Generally  speaking,  a  widget  expecting  to  interact  with  an  application  will  declare  one  or  more 
callback  lists  as  resources;  the  application  adds  functions  to  these  callback  lists,  which  will  be 
invoked  whenever  the  predefined  callback  conditions  are  met.  Callback  lists  are  resources,  so 
that  the  application  can  set  or  change  the  function  that  will  be  invoked. 

Callbacks  are  not  necessarily  invoked  in  response  to  any  event;  a  widget  can  call  the  specified 
routines  at  any  arbitrary  point  in  its  code,  whenever  it  wants  to  provide  a  "hook"  for  application 
interaction.  For  example,  all  widgets  provide  an  xtNdestroyCallback  resource  to  allow 
applications  to  interpose  a  routine  to  be  executed  when  the  widget  is  destroyed. 

Widgets  can  define  additional  callback  lists  as  they  see  fit.  For  example,  the  Athena  Command 
widget  defines  the  XtNcallback  callback  list  to  notify  clients  when  the  widget  has  been 
activated  (by  the  user  clicking  on  it  with  the  pointer).  (This  is  actually  a  poor  choice  of  names. 
It  should  have  been  given  a  more  specific  name,  such  as  xtNnotif  yCallback.) 

Callback  functions  are  registered  with  a  widget  using  a  call  to  XtAddCallbacks  or  xtAdd- 
Callback.  Even  though  callback  lists  are  resources,  callback  functions  cannot  be  added  from 
resource  files,  since  callback  lists  are  maintained  in  a  private  internal  form  by  the  Intrinsics. 
They  cannot  be  modified  directly  except  through  one  of  the  calls  (such  as  xtAddCallback) 
provided  to  access  them. 

XtAddCallbacks  adds  new  callbacks  to  the  end  of  the  callback  list.  A  callback  will  be 
invoked  as  many  times  as  it  occurs  in  the  callback  list.  See  xtCallbackProc(2)  for  a 
description  of  the  format  of  a  callback  function. 

Use  XtAddCallback  to  add  a  single  callback  to  a  widget's  callback  list. 

Callbacks  differ  from  actions  in  the  way  that  the  registered  function  is  invoked.  For  callbacks, 
the  trigger  is  an  abstract  occurrence  defined  by  the  widget,  which  may  or  may  not  be  event- 
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related.  The  routines  on  a  widget's  callback  lists  are  invoked  by  the  widget  code,  using  a  call 
to  xtCallCallbacks.  Actions,  on  the  other  hand,  are  invoked  directly  by  Xt,  as  the  result 
of  an  event  combination  specified  by  the  translations  mechanism. 

Another  major  difference  between  an  action  function  and  a  callback  function  is  that  action 
functions  are  called  with  an  event  as  an  argument,  while  actions  do  not  have  the 
client_data  or  call_data  arguments  present  for  callback  functions.  This  means  the 
only  way  to  pass  application  data  into  an  action  function  is  through  global  variables.  On  the 
other  hand,  the  presence  of  the  event  argument  means  that  you  can  use  the  contents  of  the  event 
structure  in  the  action  function. 

There  are  many  cases  where  you  might  want  to  add  more  than  one  callback  function  to  the 
same  callback  list.  The  use  of  XtCallbackExclusive  et  al.  provides  a  good  case  in  point. 
There  are  Intrinsics-defined  callback  functions  that  can  be  used  to  pop  up  a  widget.  However, 
they  do  not  place  the  pop  up. 

To  pop  up  a  dialog  box  upon  the  press  of  a  command  button,  you  would  typically  add  two  call 
back  functions  to  the  Command  widget's  xtNcallback  list:  one  of  the  Intrinsics-supplied 
xtCallback*  functions,  and  one  of  your  own  to  place  the  pop  up. 

One  way  to  add  more  then  one  callback  function  is  to  call  xtAddCallback  more  than  once. 
Another  way  is  to  call  XtAddCallbackS,  which  takes  an  xtCallbackRect  array  as  an 
argument.  This  array  is  usually  initialized  at  compile  time,  as  shown  in  the  example  below. 
The  final  NULL,  NULL  entry  terminates  the  list.  (This  particular  list  registers  the  functions 
place_jpopup  and  XtCallbackExclusive  and  passes  them  both  0  as  clie/it_data.) 

XtCallbackRec   quit_callback_list [ ]    =    { 
{place_popup,    0} 
{XtCallbackExclusive,    0}, 
{ (XtCallbackProc)    NULL,     (caddr_t)    NULL}, 

}; 

This  form  of  XtCallbackRec  list  can  also  be  used  to  replace  a  callback  list  with  xtSet- 
Values  (but  not  to  get  a  callback  list,  because  Xt  compiles  the  list  into  an  internal  form). 

Structures 

typedef  struct  _XtCallbackRec*    XtCallbackList; 

typedef  struct  _XtCallbackRec  { 

XtCallbackProc  callback; 

caddr_t  client_data; 
}  XtCallbackRec,  *XtCallbackList; 

See  Also 

XtAddCallback(l),  XtCallCallbacks(\\  XtRemoveAllCallbacks(\\  XtRemoveCallback(\),  XtRemove- 

Callbacks(\\ 

XtCallbackProc(2\ 
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Name 

XtAddConverter  —  register  a  new  resource  converter. 

Synopsis 

void  XtAddConverter (from_type,  to_type,  converter,  convert_args,  num_args) 
String  from_type; 
String  to_type; 
XtConverter  converter; 
XtConvertArgList  convert_args; 
Cardinal  num_args; 

Arguments 

from_type          Specifies  the  source  type  of  the  resource  to  be  converted. 

to_type  Specifies  the  destination  type  to  which  the  resource  is  to  be  converted. 

converter         Specifies  the  converter  procedure.  SeextConverter(2). 

convert_args  Specifies  how  to  obtain  additional  arguments  needed  for  the  conversion;  if  no 
arguments  are  provided,  this  should  be  NULL.  See  the  Structures  section 
below  for  a  detailed  description  of  the  format  of  con  vert_args. 

num_args  Specifies  the  number  of  additional  arguments  to  the  converter  or  zero. 

Description 

XtAddConverter  has  been  superseded  by  XtSetTypeConverter.  XtAddConverter 
obtains  the  default  application  context  and  invokes  xtAppAddConverter.  XtAdd 
Converter  is  a  simplified  interface  to  XtAppAddConverter,  and  the  calling  sequences 
are  identical,  except  that  you  do  not  need  to  specify  an  application  context.  Since  most  appli 
cations  have  only  one  application  context,  XtAddConverter  does  not  require  the  application 
to  pass  app_context  explicitly.  See  XtAppAddConverter  for  additional  details.  See 
XtConverter(2)  for  a  description  of  the  contents  of  a  resource  converter  function. 

Structures 

typedef  struct  { 

XtAddressMode    address_mode; 

caddr_t         address_id; 

Cardinal        size; 

}  XtConvertArgRec,  * XtConvertArgList ; 

See  Also 

XtAppAddConverter  ( 1 ), 
XtConverter (2). 
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Xt -Event  Handling  — 

Name 

XtAddEventHandler  —  register  a  procedure  to  handle  events. 

Synopsis 

void  XtAddEventHandler ( wr  event_mask,  nonmaskable,  proc,  client  data) 
Widget  w; 

EventMask  event_mask; 
Boolean  nonmaskable; 
XtEventHandler  proc; 
XtPointer  client_data; 

Arguments 

w  Specifies  the  widget  for  which  this  event  handler  is  being  registered. 

eventjmask       Specifies  the  event  mask  for  which  to  call  this  procedure. 

nonmaskable  Specifies  a  Boolean  value  that  indicates  whether  this  procedure  should  be 
called  on  the  nonmaskable  events.  (This  argument  should  almost  always  be 
False.) 

proc  Specifies  the  procedure  that  is  to  be  called.  See  xtEventHandler(2). 

client_data      Specifies  additional  data  to  be  passed  to  the  client's  event  handler. 

Description 

XtAddEventHandler  registers  with  the  dispatch  mechanism.  The  procedure  thus  registered 
will  be  called  when  an  event  matching  the  eventjmask  occurs  in  the  specified  widget.  Xt 
AddEventHandler  can  be  called  at  any  time  during  the  widget's  lifetime;  it  ensures  that 
Xlib  will  deliver  the  requested  event  by  calling  XSelect  Input  directly  if  the  widget  is  real 
ized,  and  it  ORs  the  mask  bits  into  the  widget's  event  mask  otherwise.  (Compare  XtAddRaw- 
EventHandler.) 

See  xtEventHandler(2)  for  a  description  of  an  event  handler  procedure. 

A  procedure  may  be  registered  with  the  same  client_data  to  handle  multiple  events.  Fur 
ther,  more  than  one  event  handler  can  be  registered  for  a  given  event.  If  multiple  handlers  are 
registered,  the  handlers  will  be  called,  but  in  an  indeterminate  order.  Translations  and  event 
handlers  can  also  be  registered  for  the  same  event 

If  a  widget  should  wish  to  be  informed  when  a  nonmaskable  event  occurs,  nonmaskable 
should  be  set  to  True.  The  nonmaskable  events  are  GraphicsExpose,  NoExpose, 
SelectionClear,  SelectionRequest,  SelectionNotify,  ClientMessage,  and 
MappingNotify.  Ordinarily,  nonmaskable  events  are  of  interest  only  to  the  Intrinsics. 

Chapter  8,  More  Input  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Man 
ual,  provides  example  code  for  tracking  pointer  motion,  pointer  motion  hints,  and  keyboard 
events. 
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(continued) 


XtAddEventHandler 


Structures 

The  even  t_mask  is  formed  by  combining  the  event  mask  symbols  listed  in  the  first  column  of 
the  table  below  using  the  bitwise  OR  operator  (|).  Each  mask  symbol  sets  a  bit  in  the 
even  t_mask. 

The  table  also  briefly  describes  the  circumstances  under  which  you  would  want  to  specify  each 
symbol. 


Event  Mask  Symbol 


NoEventMask 

KeyPressMask 

KeyReleaseMask 

ButtonPressMask 

ButtonReleaseMask 

EnterWindowMask 

LeaveWindowMask 

Point erMotionMask 

Point erMotionHintMask 

ButtonlMotionMask 

Button2MotionMask 

ButtonSMotionMask 

Button4MotionMask 

ButtonSMotionMask 

ButtonMotionMask 

KeymapStateMask 

ExposureMask 

VisibilityChangeMask 
Struct ureNotifyMask 
ResizeRedirectMask 
Subs truct ureNotifyMask 
SubstructureRedirectMask 
FocusChangeMask 
PropertyChangeMask 
ColormapChangeMask 
Owner GrabButtonMask 


Circumstances 


No  events 

Keyboard  down  events 

Keyboard  up  events 

Pointer  button  down  events 

Pointer  button  up  events 

Pointer  window  entry  events 

Pointer  window  leave  events 

All  pointer  motion  events 

Fewer  pointer  motion  events 

Pointer  motion  while  button  1  down 

Pointer  motion  while  button  2  down 

Pointer  motion  while  button  3  down 

Pointer  motion  while  button  4  down 

Pointer  motion  while  button  5  down 

Pointer  motion  while  any  button  down 

Any  keyboard  state  change  on  EnterNotif  y, 

LeaveNotif  y,  Focusln  or  FocusOut 

Any  exposure  (except  Graphics  Expose  and 

NoExpose) 

Any  change  in  visibility 

Any  change  in  window  configuration. 

Redirect  resize  of  this  window 

Notify  about  reconfiguration  of  children 

Redirect  reconfiguration  of  children 

Any  change  in  keyboard  focus 

Any  change  in  property 

Any  change  in  colormap 

Modifies  handling  of  pointer  events 


See  Also 

XtAddRowEventHandler(\\XtInsertEventHandler(l),XtRemoveEventHandler(l), 
XtEventHandler(2). 
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XtAddExposureToRegion 

Xt  -  Event  Handling  — 

XtAddExposureToRegion  —  merge  Expose  and  GraphicsExpose  events  into  a  region. 
Synopsis 

void   XtAddExposureToRegion (event,    region) 
XEvent    *event; 
Region   region; 

Arguments 

event  Specifies  a  pointer  to  the  Expose  or  GraphicsExpose  event 

regi  on  Specifies  the  region  object  (as  defined  in  <XlllXutil.h>). 

Description 

The  XtAddExposureToRegion  utility  function  merges  Expose  and  GraphicsExpose 
events  into  a  region  that  clients  can  process  at  once  instead  of  processing  individual  rectangles. 

XtAddExposureToRegion  computes  the  union  of  the  rectangle  defined  by  the  exposure 
event  and  the  specified  region.  Then  it  stores  the  results  back  in  region.  The  Intrinsics 
pass  an  XRegion  to  a  widget  in  the  xtExposure  method. 

If  the  event  argument  is  not  an  Expose  or  GraphicsExpose  event,  XtAddExposure 
ToRegion  returns  without  an  error  and  without  modifying  region. 

This  function  is  used  by  the  Intrinsics  exposure  compression  mechanism.  It  is  not  ordinarily 
used  explicitly  by  widgets. 

Structures 

Region  is  a  pointer  to  an  opaque  type.  ,.r 

See  Also 

Core(3) 
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Name 

XtAddGrab  —  redirect  user  input  to  a  modal  widget. 

Synopsis 

void  XtAddGrab  { w,    exclusive,    spring_loaded) 
Widget    w; 

Boolean   exclusive; 
Boolean   spring_loaded; 

Arguments 

w  Specifies  the  widget  to  add  to  the  modal  cascade. 

excl  usi  ve          Specifies  whether  user  events  should  be  dispatched  exclusively  to  this  widget 
or  also  to  previous  widgets  in  the  cascade. 

spring_loaded  Specifies  whether  this  widget  was  popped  up  because  the  user  pressed  a 
pointer  button. 

Description 

XtAddGrab  appends  a  widget  to  a  modal  cascade.  Modal  widgets  are  widgets  that,  except  for 
the  input  directly  to  them,  lock  out  user  input  to  the  application.  XtAddGrab  affects  only  Xt's 
event  dispatching — it  does  not  request  a  key  or  button  grab  on  the  server. 

When  a  modal  menu  or  modal  dialog  box  is  popped  up,  user  events  (keyboard  and  pointer 
events)  that  occur  outside  the  modal  widget  should  either  be  delivered  to  the  modal  widget  or 
be  ignored.  In  no  case  should  user  events  be  delivered  to  a  widget  outside  the  modal  widget. 

Menus  can  pop  up  submenus,  and  dialog  boxes  can  pop  up  further  dialog  boxes  to  create  a 
pop-up  cascade.  In  this  case,  user  events  may  be  delivered  to  one  of  several  modal  widgets  in 
the  cascade. 

Display-related  events  should  be  delivered  outside  the  modal  cascade  so  that  Expose  events 
and  the  like  keep  the  application's  display  up  to  date.  Any  event  that  occurs  within  the  cascade 
is  delivered  as  usual.  The  user  events  that  are  delivered  to  the  most  recent  spring-loaded  shell 
in  the  cascade  when  they  occur  outside  the  cascade  are  called  remap  events.  These  events  are 
KeyPress,  KeyRelease,  ButtonPress,  and  ButtonRelease.  The  user  events  that  are 
ignored  when  they  occur  outside  the  cascade  are  MotionNotify  and  EnterNotify.  All 
other  events  are  delivered  normally.  In  particular,  note  that  this  is  one  way  in  which  widgets 
can  receive  LeaveNotify  events  without  first  receiving  EnterNotify  events;  they  should 
be  prepared  to  deal  with  this,  typically  by  ignoring  the  unmatched  LeaveNotify  events. 

XtPopup  uses  the  XtAddGrab  and  XtRemoveGrab  functions  to  constrain  user  events  to  a 
modal  cascade  and  subsequently  to  remove  a  grab  when  the  modal  widget  goes  away.  Usually 
you  should  have  no  need  to  call  them  explicitly.  XtAddGrab  is  called  implicitly  by  xt- 
CallbackExclusive  and  other  calls. 

The  XtAddGrab  function  appends  the  widget  (and  associated  parameters)  to  the  modal  cas 
cade  and  checks  that  exclusive  is  True  if  spring_loaded  is  True.  If  these  are  not 
both  True,  XtAddGrab  generates  a  warning  message  and  asserts  an  exclusive  grab  any 
way. 
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When  the  modal  cascade  holds  at  least  one  widget,  XtDispatchEvent  determines  if  the 
event  should  be  delivered  or  held.  It  starts  with  the  last  cascade  entry  and  follows  the  cascade 
till  it  finds  the  youngest  cascade  entry  added  with  exclusive  True.  If  it  finds  a  widget  in 
the  cascade  interested  in  the  event,  it  delivers  the  event  to  it 

This  modal  cascade,  along  with  all  descendants  of  the  widgets  it  contains,  comprise  the  active 
subset.  User  events  that  occur  outside  the  widgets  in  this  subset  are  ignored  or  remapped. 
Modal  menus  generally  add  pop-up  submenus  to  the  cascade  with  exclusive  set  to  False, 
so  that  the  submenu  can  receive  input  event  after  it  pops  up.  Modal  dialog  boxes  that  restrict 
user  input  to  the  most  deeply  nested  dialog  box  add  a  subdialog  widget  to  the  cascade  with 
exclusive  set  to  True.  User  events  that  occur  within  the  active  subset  are  delivered  to  the 
appropriate  widget,  which  is  usually  a  descendant  of  the  modal  widget 

Regardless  of  where  in  the  application  they  occur,  remap  events  are  always  delivered  to  the 
most  recent  widget  in  the  active  subset  of  the  cascade  registered  with  spring_loaded 
True,  if  any  such  widget  exists.  If  the  event  occurred  in  the  active  subset  of  the  cascade  but 
outside  the  spring-loaded  widget,  the  event  is  delivered  normally  before  being  delivered  also  to 
the  spring-loaded  widget 

See  Also 

XtCallbackExclusive(l),  XtCreatePopupShell(\\  XtDispatchEvent(l),  XtPopup(\),  XtRemoveGrab(\). 


74 


X  Toolkit  Intrinsics  Reference  Manual 


—  Xt -Event  Handling- 


f  XtAddlnput 


Name 

XtAddlnput  —  register  a  new  file  as  an  input  source  for  an  application. 

Synopsis 

Xtlnputld  XtAddlnput (source,  condition,  proc,  client_data) 
int  source; 
XtPointer  condition; 
XtlnputCallbackProc  proc; 
XtPointer  client_data; 

Arguments 

source  Specifies  the  source  file  descriptor  (on  a  POSDC-based  system)  or  other 

operating-system-dependent  device  specification. 

condition          Specifies  a  mask  that  indicates  a  read,  write,  or  exception  condition  or  some 
operating-system-dependent  condition. 

proc  Specifies  the  procedure  that  is  to  be  called  when  input  is  available.  Seext- 

InputCallbackProc(2). 

client_data      Specifies  the  argument  to  be  passed  to  the  specified  procedure  when  input  is 
available. 

Description 

XtAddlnput  has  been  superseded  by  xtAppAddlnput. 

While  most  applications  are  driven  only  by  X  events,  some  applications  need  to  incorporate 
other  sources  of  input.  XtAppAddlnput  allows  an  application  to  integrate  notification  of 
pending  file  data  into  the  event  mechanism.  The  application  uses  XtAppAddlnput  to  regis 
ter  a  file  with  the  Intrinsics  read  routine.  When  I/O  is  pending  on  the  file  source,  the  regis 
tered  callback  procedure  proc  is  invoked,  source  is  usually  file  input  but  can  also  be  file 
output.  (Note  that  "file"  means  any  sink  or  source  of  data.) 

XtAppAddlnput  also  specifies  the  condition  under  which  source  can  generate  events. 
The  legal  values  for  condition  are  operating-system-dependent.  On  a  POSK-based  system, 
the  possible  values  are  XtlnputReadMask,  XtlnputWriteMask,  or  XtlnputExcept- 
Mask.  The  masks  cannot  be  ORed  together.  These  limit  the  invocation  of  proc  to  either  a 
pending  read,  write,  or  exception  condition  on  the  source  file.  See  the  POSIX  system  select 
call  for  discussion  of  these  conditions. 

Note  that  when  reading  from  a  socket,  you  should  be  careful  not  to  close  the  end  of  the  socket 
that  is  waiting  before  exiting  the  XtAppMainLoop.  If  you  do  this,  you  will  get  an  infinite 
loop,  in  which  the  proc  is  called  repeatedly,  while  the  Intrinsics  wait  for  an  EOF  to  be  read. 

See  Chapter  8,  More  Input  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming 
Manual,  for  a  complete  example  using  this  function. 

See  Also 

XtAppAddInput(\\  XtRemoveInput(\\ 
XtlnputCallbackProc  (2). 


X  Toolkit  Intrinsics  Reference  Manual  75 


XtAddRawEventHandler  vi 

Xt-  Event  Handling— 

Name 

XtAddRawEventHandler  —  register  an  event  handler  without  selecting  for  the  event. 

Synopsis 

void  XtAddRawEventHandler (w,  event_mask,  nonmaskable,  proc,  client_data) 
Widget  w; 

EventMask  event_mask; 
Boolean  nonmaskable; 
XtEventHandler  proc; 
XtPointer  clie/it_data; 

Arguments 

w  Specifies  the  widget  for  which  this  event  handler  is  being  registered. 

even t_mask  Specifies  the  event  mask  for  which  to  call  this  procedure.  See  xtAdd- 
EventHandler. 

nonmaskable  Specifies  a  Boolean  value  that  indicates  whether  this  procedure  should  be 
called  on  the  nonmaskable  events  (GraphicsExpose,  NoExpose, 
SelectionClear,  SelectionRequest,  SelectionNotify, 
ClientMessage,  and  MappingNotif  y ) . 

proc  Specifies  the  procedure  that  is  to  be  registered.  See  xtEventHandler(2). 

client_data      Specifies  additional  data  to  be  passed  to  the  client's  event  handler. 

Description 

XtAddRawEventHandler  is  similar  to  xtAddEventHandler  except.that  it  never  causes 
an  XSelect Input  call  to  be  made  for  its  events.  The  event  mask  in  XtAddRawEvent 
Handler  indicates  which  events  the  handler  will  be  called  in  response  to,  but  only  when  these 
events  are  selected  elsewhere. 

A  raw  event  handler  might  be  used  to  "shadow"  another  event  handler  (both  added  with  the 
same  event  mask),  such  that  until  a  primary  event  handler  is  added,  the  shadow  handler  will 
never  be  called.  The  primary  handler  will  be  added  with  XtAddEventHandler  and  will 
alter  the  event  mask,  and  then  both  handlers  will  be  called  when  the  appropriate  events  occur. 

However,  the  "shadowing"  technique  is  not  necessary  to  assure  that  multiple  calls  to  XtAdd 
EventHandler  would  not  result  in  wasted  XSelect  input  calls  in  which  the  event  mask 
has  not  changed.  Xt  keeps  a  cache  of  the  event  masks  of  each  widget  and  calls  XSelect - 
Input  only  when  it  is  necessary  to  change  the  window's  event  mask  attribute. 

Raw  event  handlers  are  removed  with  a  call  to  XtRemoveRawEvent Handler. 

A  widget  needs  to  register  a  raw  handler  only  in  extraordinary  circumstances;  most  widgets  use 
XtAddEventHandler. 
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(continued) 


XtAddRawEventHandler 


See  Also 

XtAddEventHandler ( 1 ),  XtRemoveRawEventHandler(\\ 
XtEventHandler(2). 
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XtAddTimeOut  \ Y 

N Xt  -  Event  Handling  — 

Name 

XtAddTimeOut  —  create  a  timeout  value. 

Synopsis 

Xtlntervalld  XtAddTimeOut (interval,  proc,  client_data) 
unsigned  long  interval; 
XtTimerCallbackProc  proc; 
XtPointer  client_data; 

Arguments 

interval  Specifies  the  time  interval  in  milliseconds. 

proc  Specifies  the  procedure  to  be  called  when  the  time  expires.  See  xt  Timer - 

CallbackProc(2). 

client_data      Specifies  the  argument  to  be  passed  to  the  specified  procedure  when  it  is 
called. 

Description 

XtAddTimeOut  has  been  superseded  by  XtAppAddTimeOut. 

The  Intrinsics  invoke  the  specified  proc  when  interval  elapses  and  the  timeout  is  removed 
from  the  event  queue. 

The  return  value  XtlntervallD  uniquely  identifies  the  pending  timer  pseudo-event.   The 
pending  event  can  be  deleted  from  the  queue  before  the  interval  expires  by  calling  xt- 

RemoveTimeOut. 

The  callback  procedure  pointer  that  is  invoked  when  timeouts  expire  is  of  type  XtTimer 
CallbackProc. 

XtAppNextEvent  and  xtAppPeekEvent  dispatch  timer  queue  entries. 
See  Also 

XtAppAddTimeOut(\\  XtAppNextEvent(l),  XtAppPeekEvent(\\  XtAppP  ending  (\\  XtDispatchEvent(\), 
XtRemoveTimeOut  ( 1 ), 
XffimerCallbackProc  (2). 
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c      u  M   f  XtAddWorkProc 

— Xt  -  Event  Handling ' 

Name 

XtAddWorkProc  —  register  a  work  procedure  for  an  application. 

Synopsis 

XtWorkProcId  XtAddWorkProc (proc,  client_data) 
XtWorkProc  proc; 
XtPointer  client_data; 

Arguments 

proc  Specifies  the  procedure  to  be  called  when  the  application  is  idle. 

dient_data      Specifies  the  argument  to  be  passed  to  the  specified  procedure  when  it  is 
called. 

Description 

XtAddWorkProc  has  been  superseded  by  xtAppAddWorkProc.  XtAddWorkProc  regis 
ters  a  function  that  will  be  called  by  Xt  when  there  are  no  events  or  other  input  to  process. 

XtWorkProc(2)  discusses  the  responsibilities  of  the  application's  background  processing  rou 
tine. 

See  Also 

XtAppAddWorkProc(l\XtRemoveWorkProc(l\ 
XtWorkProc(2). 
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XtAppAddActionHook  _ 

v Xt  -  Translations  and  Actions — 

Name 

XtAppAddActionHook  —  add  an  action  hook. 

Synopsis 

XtActionHookld  XtAppAddActionHook (app,  proc,  client_data) 
XtAppContext  app; 
XtActionHookProc  proc; 
XtPointer  client_data; 

Arguments 

app  Specifies  the  application  context. 

proc  Specifies  the  action  hook  procedure. 

dient_data      Specifies  application-specific  data  to  be  passed  to  the  action  hook. 

Description 

XtAppAddActionHook  adds  the  specified  procedure  to  the  front  of  an  action  list  for  a  par 
ticular  application  context.  In  the  future,  when  any  action  routine  is  about  to  be  invoked  for 
any  widget  in  this  application  context,  either  through  the  translation  manager  or  via  xtCall- 
ActionProc,  the  action  hook  procedures  will  be  called  in  reverse  order  of  registration  just 
prior  to  invoking  the  action  routine. 

Action  hook  procedures  are  removed  automatically  and  the  xtActionHookids  destroyed 
when  the  application  context  in  which  they  were  added  is  destroyed. 

Action  hooks  can  be  used  to  record  user  actions  for  later  playback  using  xtCallAction- 
Proc.  This  is  one  way  to  implement  keyboard  macros. 

See  Also 

XtAppAddActions(\\  XtCollActionProc(\). 
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— Xt  -  Translations  and  Actions- 


XtAppAddActions 


Name 

XtAppAddActions  —  declare  an  action  table  and  register  it  with  the  Resource  Manager. 

Synopsis 

void  XtAppAddActions (app_ con text,  actions,  num_actions) 
XtAppContext  app_ context; 
XtActionList  actions; 
Cardinal  num_actions; 

Arguments 

app_context      Specifies  the  application  context. 

actions  Specifies  the  action  table  to  register. 

num_args  Specifies  the  number  of  entries  in  this  action  table. 

Description 

All  widget  class  records  contain  an  action  table.  In  addition,  using  XtAppAddActions,  an 
application  can  register  its  own  action  tables  with  the  Resource  Manager.  An  action  table  con 
sists  of  a  list  of  string  names  (which  can  be  used  in  translation  tables  to  associate  an  action  with 
one  or  more  events)  and  corresponding  function  pointers.  The  function  pointer  is  of  type  xt- 
ActionProc. 

By  convention,  the  string  and  the  function  name  are  identical  except  that  the  function  name 
begins  with  an  upper-case  letter,  as  in  the  example: 

static  XtActionsRec  two_quits[]  =  { 

{"confirm",  Confirm}, 

{"quit",  Quit}, 
}, 

This  mapping  from  strings  to  function  pointers  is  necessary  to  allow  translation  tables  to  be 
specified  in  resource  files,  which  are  made  up  entirely  of  strings. 

For  example,  the  Command  widget  has  procedures  to  take  the  following  actions: 

•  Set  the  appearance  of  the  Command  widget  to  indicate  it  is  activated  when  a  pointer  but 
ton  has  been  pressed  in  it. 

•  Unset  the  button  back  to  its  normal  mode. 

•  Highlight  the  button  borders  when  the  pointer  enters  the  Command  widget. 

•  Unhighlight  the  button  borders  when  the  pointer  leaves. 

•  Notify  any  callbacks  that  the  button  has  been  activated. 

The  action  table  for  the  Command  widget  class  makes  these  functions  available  to  translation 
tables  written  for  Command  or  any  subclass: 

XtActionsRec  actionTable [ ]  =  { 
{"Set",  Set}, 
{"Unset",        Unset}, 
{"Highlight",    Highlight}, 
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{"Unhighlight",     Unhighlight} 
{"Notify",  Notify}, 

}; 

The  actions  specified  in  a  translation  can  be  registered  before  or  after  the  translation  table  is 
parsed. 

The  items  in  an  action  list  registered  with  xtAddActions  are  registered  globally  for  the 
entire  application.  By  contrast,  the  action  list  specified  in  a  widget  class  structure  is 
local — only  translations  specified  by  the  widget  itself  can  access  local  actions.  However,  a 
widget's  local  translation  can  access  global  actions,  if  there  is  no  local  action  of  the  same  name. 

If  an  application  registers  more  than  one  global  action  with  the  same  name,  the  most  recently 
registered  action  is  used.  The  Intrinsics  register  an  action  table  for  xtMenuPopup  and  xt- 

MenuPopdown  as  part  of  XtCreateApplicationContext. 

The  Core  class  structure  holds  a  list  of  translations  and  actions.  Compare  xtParse- 
TranslationTable.  Chapter  7,  Events,  Translations,  and  Accelerators,  in  Volume 
Four,  X  Toolkit  Intrinsics  Programming  Manual,  contains  general  discussion  and  examples. 

If  more  than  one  action  is  registered  with  the  same  name,  the  most  recently  registered  action  is 
used.  If  duplicate  actions  exist  in  an  action  table,  the  first  is  used.  The  Intrinsics  register  an 
action  table  for  actions  called  MenuPopup  and  MenuPopdown  as  part  of  X  Toolkit  initializa 
tion. 

See  Also 

XtActionProc  (2),  XtAppAddActionHook  (2). 
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XtAppAddConverter 


Name 

XtAppAddConverter  —  register  a  new  resource  converter  for  an  application. 

Synopsis 

XtAppAddConverter (app_context,  from_type,  to_type,  converter,  convert_args, 

num_args) 

XtAppContext  app_context; 
String  from_type; 
String  to_type; 
XtConverter  converter; 
XtConvertArgList  convert_args; 
Cardinal  num  args; 


Arguments 

app_context 
from_type 
to_type 
converter 
convert  args 


num_args 


Specifies  the  application  context. 

Specifies  the  source  type  of  the  resource  to  be  converted. 

Specifies  the  destination  type  to  which  the  resource  is  to  be  converted. 

Specifies  the  converter  procedure.  See  xtConverter(2). 

Specifies  how  to  obtain  additional  arguments  needed  for  the  conversion;  if 
no  arguments  are  provided,  this  should  be  NULL.  See  the  Structures  sec 
tion  below  for  a  detailed  description  of  the  format  of  con vert_args. 

Specifies  the  number  of  additional  arguments  to  the  converter  or  zero. 


Description 

XtAppAddConverter  has  been  superseded  by  xtSetTypeConverter.  Resource 
converters  provide  a  general  way  to  pass  specific  data  structures,  and  to  hide  the  details  of  the 
data  structures  themselves.  Using  XtAppAddConverter  or  XtAddConverter,  an  appli 
cation  can  register  a  converter  to  transform  data  of  a  given  type  to  another  specified  type.  The 
types  themselves  are  arbitrary,  and  are  specified  by  a  string.  For  example,  the  converter  mecha 
nism  can  convert  data  of  type  String  to  an  application  data  type  of  Menu  if  the  application 
has  registered  the  appropriate  converter;  to  the  application,  the  data  type  Menu  is  opaque. 

Some  converters  need  additional  arguments,  which  can  be  obtained  from  fields  within  the 
widget  or  as  constants.  The  enumerated  type  xtAddressMode  and  the  structure  xt- 
ConvertArgRec  specify  how  each  argument  is  derived.  These  are  defined  in 
<X11  /Convert. h>,  as  follows: 

typedef  enum  { 

/*  address  mode  parameter  representation  */ 

XtAddress,  /*  address  */ 

XtBaseOffset,  /*  offset  */ 

Xtlmmediate  /*  constant  */ 

XtResourceString  /*  resource  name  string  */ 

XtResourceQuark  /*  resource  name  quark  */ 
}  XtAddressMode; 

typedef  struct  { 
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XtAddressMode   address_mode; 
caddr_t   address_id; 
Cardinal    size; 
}    XtConvertArgRec,    *XtConvertArgList; 

The  address_mode  member  specifies  how  to  interpret  the  address_id  member: 
XtAddress  causes  address_id  to  be  interpreted  as  the  address  of  the  data. 

XtBaseOf  f  set  causes  address_id  to  be  interpreted  as  the  offset  from  the  widget 

base. 

Xtlmmediate  causes  address_id  to  be  interpreted  as  a  constant. 

XtResourceString  causes  address_id  to  be  interpreted  as  the  name  of  a  resource  to  be 
converted  into  an  offset  from  the  widget  base. 

XtResourceQuark  means  address_id  is  an  internal  compiled  form  of  an  Xt 
ResourceString.  The  size  field  specifies  the  length  of  the  data  in 
bytes. 

Assuming  a  routine  called  CvtStringToPixel  (see  xtConverter  for  an  example  of  this 
converter),  the  following  code  registers  the  routine  as  an  official  resource  converter: 

static   XtConvertArgRec   colorConvertArgs [ ]    =    { 

{XtBaseOf f set,     (caddr_t)    XtOff set (Widget ,    core . screen) , 

sizeof (Screen    *)}, 

{XtBaseOf f set,     (caddr_t)    XtOffset (Widget,    core .colormap) , 
sizeof (Colormap) } 

}; 

» 

XtAddConverter (XtRString,    XtRPixel,    CvtStringToPixel, 
colorConvertArgs,    XtNumber (colorConvertArgs) )  ; 

The  conversion  argument  descriptors  colorConvertArgs  and  screenConvertArg  are 
predefined.  The  screenConvertArg  descriptor  puts  the  widget's  screen  field  into 
args[0].  The  colorConvertArgs  descriptor  puts  the  widget's  screen  field  into 
args  [  0  ]  and  the  widget's  colormap  field  into  args  [  1  ] . 

Conversion  routines  should  not  just  put  a  descriptor  for  the  address  of  the  base  of  the  widget 
into  args  [  0  ]  and  then  use  that  in  the  routine.  They  should  pass  in  the  actual  values  that  the 
conversion  depends  on.  By  keeping  the  dependencies  of  the  conversion  procedure-specific,  it 
is  more  likely  that  subsequent  conversions  will  find  what  they  need  in  the  conversion  cache. 
This  way  the  cache  is  smaller  and  has  fewer  and  more  widely  applicable  entries. 

XtAddConverter  provides  a  simplified  interface  for  programs  using  the  default  application 
context. 

xtConverter(2)  explains  the  responsibilities  and  conventions  of  the  converter  function 
itself;  it  also  shows  an  example  converter,  CvtStringToPixel. 
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(continued) 


XtAppAddConverter 


See  Also 

XtCallConverter(\\  XtConvertandStore,  XtDirectConvert(\\  XtSe(TypeConverter(\), 
XtConverter(2). 
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XtAppAddlnput  \ 

v Xt  -  Event  Handling— 

Name 

XtAppAddlnput  —  register  a  new  file  as  an  input  source  for  a  given  application. 

Synopsis 

Xtlnputld  XtAppAddlnput (app_context,  source,  condition,  proc,  client_data) 
XtAppContext  app_context; 
int  source; 
XtPointer  condition; 
XtlnputCallbackProc  proc; 
XtPointer  client_data; 

Arguments 

app_  con  text      Specifies  the  application  context  that  identifies  the  application. 

source  Specifies  the  source  file  descriptor  (on  a  POSDC-based  system)  or  other 

operating-system-dependent  device  specification. 

condition         Specifies  a  mask  that  indicates  a  read,  write,  or  exception  condition  or  some 
operating-system-dependent  condition. 

proc  Specifies  the  procedure  that  is  to  be  called  when  condition  is  true.  See 

XtInputCallbackProc(2). 

client_data      Specifies  for  argument  source  to  be  passed  to  proc  when  I/O  is  available. 

Description 

While  most  applications  are  driven  only  by  X  events,  some  applications  need  to  incorporate 
other  sources  of  input.  XtAppAddlnput  allows  an  application  to  integrate  notification  of 
pending  file  data  into  the  event  mechanism.  The  application  uses  XtAppAddlnput  to  regis 
ter  a  file  with  the  Intrinsics  read  routine.  When  I/O  is  pending  on  the  file  source,  the  regis 
tered  callback  procedure  proc  is  invoked,  source  is  usually  file  input  but  can  also  be  file 
output  (Note  that  "file"  means  any  sink  or  source  of  data.) 

XtAppAddlnput  also  specifies  the  condition  under  which  source  can  generate  events. 
The  legal  values  for  condition  are  operating-system-dependent.  On  a  POSIX-based  system, 
the  possible  values  are  XtlnputReadMask,  XtlnputWriteMask,  or  XtlnputExcept- 
Mask.  The  masks  cannot  be  ORed  together.  These  limit  the  invocation  of  proc  to  either  a 
pending  read,  write,  or  exception  condition  on  the  source  file.  See  the  POSIX  system  select 
call  for  discussion  of  these  conditions. 

Callback  procedures  that  are  used  when  there  are  file  events  are  of  type  XtlnputCallback 
Proc. 

Note  that  when  reading  from  a  socket,  you  should  be  careful  not  to  close  the  end  of  the  socket 
that  is  waiting  before  exiting  the  xtAppMainLoop.  If  you  do  this,  you  will  get  an  infinite 
loop,  in  which  the  proc  is  called  repeatedly,  while  the  Intrinsics  wait  for  an  EOF  to  be  read. 

See  Chapter  8,  More  Input  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming 
Manual,  for  a  complete  example  using  this  function. 
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(continued) 


XtAppAddlnput 


See  Also 

XtRemove/nput(l), 
XtlnputCallbackProc  (2). 
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XtAppAddTimeOut  Y| 

x X\  -  Event  Handling 

XtAppAddTimeOut  —  invoke  a  procedure  after  a  specified  timeout. 
Synopsis 

Xtlntervalld  XtAppAddTimeOut (app_ con text,  interval,  proc,  client_data) 
XtAppContext  app_context; 
unsigned  long  interval; 
XtTimerCallbackProc  proc; 
XtPointer  client_data; 

Arguments 

app_  con  text      Specifies  the  application  context  for  which  the  timer  is  to  be  set. 

interval  Specifies  the  time  interval  in  milliseconds. 

proc  Specifies  the  procedure  that  is  to  be  called  when  the  time  expires.  See  xt- 

TimerCallbackProc(2). 

client_data      Specifies  the  argument  to  be  passed  to  the  specified  procedure  when  it  is 
called. 

Description 

XtAppAddTimeOut  allows  a  program  to  have  a  function  called  after  a  specified  timeout. 
XtAppAddTimeOut  creates  the  timeout  and  returns  an  identifier  for  it.  The  length  of  the 
timeout  value  is  interval  milliseconds. 

The  Intrinsics  invoke  the  specified  callback  when  interval  elapses,  and  the  timeout  is 
removed  from  the  event  queue. 

The  return  value  xtlntervallD  uniquely  identifies  the  pending  timer  pseudo-event.  The 
pending  event  can  be  deleted  from  the  queue  before  the  interval  expires  by  calling  xt- 

RemoveTimeOut . 

The  callback  procedure  pointer  that  is  invoked  when  timeouts  expire  is  of  type  XtTimer 
CallbackProc. 

XtAppNextEvent  and  XtAppPeekEvent  dispatch  timer  queue  entries. 
See  Also 

XtAppNextEvent  (I),  XtAppPeekEvent(l),  XtDispotchEvent(\)t  XtRemoveTimeOut(\\ 
XfTimerCollbockProc  (2). 
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XtAppAddWorkProc 

— Xt-  Event  Handling ' 

XtAppAddWorkProc  —  register  a  work  procedure  for  a  given  application. 
Synopsis 

XtWorkProcId  XtAppAddWorkProc (app_context,  proc,  client_data) 
XtAppContext  app_context; 
XtWorkProc  proc; 
XtPointer  client_data; 

Arguments 

app_context      Specifies  the  application  context  that  identifies  the  application. 

proc  Specifies  the  procedure  that  is  to  be  called  when  the  application  is  idle. 

dient_data      Specifies  the  argument  to  be  passed  to  the  specified  procedure  when  it  is 
called. 

Description 

Xt  supports  a  limited  form  of  background  processing.  Most  applications  spend  most  of  their 
time  waiting  for  input;  to  do  useful  work  during  this  idle  time,  you  can  register  a  work  proce 
dure  that  will  run  when  the  application  would  otherwise  block  in  xtAppNext Event  or  xt- 
AppProcessEvent. 

XtAppAddWorkProc  adds  the  specified  proc  for  the  application  identified  by 
app_context.  XtWorkProcId  is  an  opaque  identifier  unique  to  this  work  procedure. 
Multiple  work  procedures  can  be  registered,  and  the  most  recently  added  one  is  always  the  one 
that  is  called.  However,  if  a  work  procedure  itself  adds  another  work  procedure,  the  newly 
added  one  has  lower  priority  than  the  current  one. 

Passing  the  XtWorkProcId  returned  from  the  XtWorkProc  to  XtRemoveWorkProc 
causes  proc  to  stop  being  called. 

Work  procedures  are  of  type  XtWorkProc.  XtWorkProc  discusses  the  responsibilities  of 
the  application's  background  processing  routine.  xtAddWorkProc  is  a  simplified  interface  to 
this  function. 

See  Also 

XtAppNextEvent(\\  XtAppProcessEvent(\\  XtRemoveWorkProc(l), 
XtWorkProc  (2). 
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XtAppCreateShell  \. 


•Xt  -Initialization  — 


Name 

XtAppCreateShell  —  create  additional  top-level  widget 

Synopsis 

Widget  XtAppCreateShell (application_name,  application_class,  widget_class, 

display,  args,  num_args) 
String  application_name; 
String  application_class; 
WidgetClass  widget_class; 
Display  *  display; 
ArgList  args; 
Cardinal  num_args; 

Arguments 

appl  icati  or._n  ame 

Specifies  the  name  of  the  application  instance.  If  this  argument  is  NULL,  the 
application  name  passed  to  XtDi  splay  Initialize  is  used. 

application_class 

Specifies  the  class  name  of  this  application. 

widget_class    Specifies  the  widget  class  that  the  application  top-level  widget  should  be 
(normally  applicationShellWidgetClass). 

display  Specifies  the  display  from  which  to  get  the  resources. 

args  Specifies  the  argument  list  to  override  other  resource  specifications. 

num_args  Specifies  the  number  of  arguments  in  the  argument  list. 

,,f 
Description 

An  application  can  have  multiple  top-level  widgets,  which  can  potentially  be  on  many  different 
screens.  The  first  shell  of  an  application  is  created  with  xtAppinitialize.  An  application 
uses  XtAppCreateShell  if  it  needs  to  have  additional  independent  windows.  (A  help  sys 
tem  that  stayed  on  the  screen  and  could  be  moved  and  resized  independently  of  the  application 
is  an  example  of  such  an  independent  top-level  window.)  The  XtAppCreateShell  function 
creates  a  top-level  widget  that  is  the  root  of  a  widget  tree. 

The  XtAppCreateShell  function  saves  the  specified  application  name  and  application  class 
for  qualifying  all  widget  resource  specifiers  and  to  set  the  WM_CLASS  property  on  the  shell's 
window,  appl i cat ion_name  and  appl i cat ion_cl ass  become  the  left-most  compo 
nents  in  all  widget  resource  names  for  this  new  application.  They  are  used  for  qualifying  all 
subsequent  widget  resource  specifiers.  The  widget  returned  by  XtAppCreateShell  has  the 
WM_COMMAND  and  WM_CLASS  properties  set  for  window  and  session  managers  if  the  speci 
fied  widget_ class  is  a  subclass  of  ApplicationShell  (see  Shell(3)). 

XtAppCreateShell  should  be  used  to  create  a  new  logical  application  within  a  program  or 
to  create  a  shell  on  another  display.  In  the  first  case,  XtAppCreateShell  allows  the  specifi 
cation  of  a  new  root  in  the  resource  hierarchy.  If  XtAppCreateShell  is  used  to  create 
shells  on  multiple  displays,  it  uses  the  resource  database  associated  with  display. 
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Xt  -  Initialization  (continued) 

The  XtNvisual  and  xtNcolormap  resources  must  be  set  while  creating  the  shell,  since 
they  are  permanent  characterstics  of  the  associated  window.  All  descendants  of  a  shell  inherit 
the  visual  and  colormap  of  the  shell. 

There  are  two  alternatives  for  creating  multiple  top-level  shells  within  a  single  (logical)  appli 
cation: 

•  Designate  one  shell  as  the  real  top-level  shell  and  create  the  others  as  pop-up  children  of 
it  by  using  XtCreatePopupShell. 

•  Have  all  shells  as  pop-up  children  of  an  unrealized  top-level  shell. 

The  first  method,  which  is  best  when  there  is  a  clear  choice  for  what  is  the  main  window,  leads 
to  resource  specifications  like  the  following: 

xmail. geometry:  .  .  .  (the  main  window) 

xmail .  read,  geometry :  .  .  .  (the  read  window) 

mail. compose. geometry:  .  .  .  (the  compose  window) 

The  second  method,  which  is  best  if  there  is  no  main  window,  leads  to  resource  specifications 
like  the  following: 

xmail.  headers,  geometry:  .  .  .         (the  headers  window) 
xmail.  read,  geometry:  .  .  .  (the  read  window) 

xmail  .compose. geometry :  .  .  .         (the  compose  window) 

XtApplnitialize  is  a  simplified  interface  to  xtCreateApplicationContext,  xt- 
Displaylnitialize,  and  XtAppCreateShell. 

See  Also 

XtApplnitialize (1),  XtCreateApplicationContext(l),  XtCreatePopupShell(l\  XtDisplayInitialize(\). 
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XtAppError  \ 

v> Xt-  Error  Handling  — 

Name 

XtAppError  —  call  the  installed  fatal  error  procedure. 

Synopsis 

void  XtAppError (app_context,  message) 
XtAppContext  app_context; 
String  message; 

Arguments 

app_context      Specifies  the  application  context. 

message  Specifies  the  message  to  be  reported. 

Description 

Xt  provides  two  levels  of  error  handling: 

•  A  high-level  interface  that  takes  an  error  name  and  class  and  looks  the  error  up  in  an 
error  resource  database. 

•  A  low-level  interface  that  takes  a  simple  string,  which  is  printed  out  as  the  error  message. 

Application-context-specific  error  handling  is  not  implemented  on  many  systems.  Most  imple 
mentations  will  have  just  one  set  of  error  handlers.  If  different  handlers  are  set  for  different 
application  contexts,  the  one  set  last  will  be  used. 

In  theory,  most  programs  should  use  XtAppErrorMsg  (or  xtErrorMsg  if  application 
contexts  are  not  being  used),  not  XtAppError  or  xtError,  so  that  the  programs  can  be  eas 
ily  customized  to  provide  international  or  other  custom  error  messages.  However,  the  low-level 
handlers  are  much  easier  to  use. 

XtAppError  calls  the  low-level  fatal  error  handler.  Fatal  errors  are  assumed  to  be  catastro 
phic  and  irrecoverable.  A  warning  error  handler  also  exists  for  errors  that  require  attention  but 
do  not  preempt  a  program  running  correctly  to  a  normal  successful  completion.  (xtApp- 
Warning  calls  the  corresponding  nonfatal  error  handler.  XtAppErrorMsg  and  xtApp- 
WarningMsg  call  the  corresponding  high-level  handlers.) 

See  Also 

XtAppErrorMsg  (I),  XtAppSetErrorHandler(\),  XtAppSetErrorMsgHandler(\\  XtAppSetWarning- 
Handler(\\  XtAppSeiWarningMsgHandler(\\  XtAppWarning(\\  XtAppWarningMsg(\\ 
XtErrorHandler(2). 
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-X,-  Error  HandNng /  XtAppElTOfMsg 

Name 

XtAppErrorMsg  —  call  the  high-level  fatal  error  handler. 

Synopsis 

void  XtAppErrorMsg (app_context,  name,  type,  class,  default,   params, 

num_params) 

XtAppContext  app_context; 
String  name; 
String  type; 
String  class; 
String  default; 
String  *params; 
Cardinal  *num_params; 

Arguments 

app_context      Specifies  the  application  context. 

name  Specifies  the  general  kind  of  error;  for  example,  InvalidParameter. 

type  Specifies  the  detailed  name  of  the  error.  This  is  specified  using  print  f -like 

syntax,  with  the  parameters  and  number  of  parameters  specified  by  params 
and  num_params. 

class  Specifies  the  resource  class. 

defa  ul  t  Specifies  the  default  message  to  use  if  no  message  is  found  in  the  database. 

params  Specifies  a  pointer  to  a  list  of  values  to  be  stored  in  the  type  argument  when 

the  message  is  generated. 

num_params       Specifies  the  number  of  values  in  the  parameter  list. 

Description 

Xt  provides  two  levels  of  error  handling: 

•  A  high-level  interface  that  takes  an  error  name  and  class  and  looks  the  error  up  in  an 
error  resource  database. 

•  A  low-level  interface  that  takes  a  simple  string,  which  is  printed  out  as  the  error  message. 

The  high-level  functions  construct  a  string  to  pass  to  the  lower-level  interface.  The  name  and 
type  arguments  are  concatenated  to  form  the  "name"  that  is  used  to  look  up  a  message  in  the 
error  database.  On  POSEX-based  systems,  the  error  database  is  usually  lusrlliblXHIXtErrorDB. 

In  theory,  most  programs  should  use  XtAppErrorMsg,  not  xtAppError,  so  that  the  pro 
grams  can  be  easily  customized  to  provide  international  or  other  custom  error  messages.  How 
ever,  the  low-level  handlers  are  much  easier  to  use. 

XtAppError  calls  the  low-level  fatal  error  handler.  Fatal  errors  are  assumed  to  be  catastro 
phic  and  irrecoverable.  A  warning  error  handler  also  exists  for  errors  that  require  attention  but 
do  not  preempt  a  program  running  correctly  to  a  normal  successful  completion.  (xtApp- 
Warning  calls  the  corresponding  non-fatal  error  handler.  XtAppErrorMsg  and  xtApp- 
WarningMsg  call  the  corresponding  high-level  handlers.) 
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XtAppErrorMsg  (continued)  Xt-  Error  Handling 

The  Intrinsics  internal  errors  all  have  class  xtToolkitError. 
See  Also 

XtAppError(l),  XtAppSetErrorHandler(\\  XtAppSetErrorMsgHandler(\\  XtAppSetWarning- 
Handler(l\  XtAppSetWarningMsgHandler(l),  XtAppWarning(\\  XtAppWarningMsg(l\ 
XtErrorHandler(2). 
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Handling /  XtAppGetErrorDatabase 

Name 

XtAppGetErrorDatabase  —  obtain  the  error  database. 

Synopsis 

XrmDatabase  *XtAppGetErrorDatabase ( app_context ) 
XtAppContext  app_context; 

Arguments 

app_context      Specifies  the  application  context. 

Description 

Xt's  high-level  error  and  warning  message  handlers  use  a  resource-like  database  for  storing 
error  messages.  On  POSDC-based  systems,  the  error  database  is  usually  stored  in  the  file 
lusrlliblXlllXtErrorDB.  However,  it  is  possible  to  have  separate  application-context-specific 
databases. 

To  obtain  the  error  database  (for  example,  to  merge  with  an  application  or  widget-specific  data 
base),  use  XtAppGetErrorDatabase. 

The  XtAppGetErrorDatabase  function  returns  the  address  of  the  error  database.  The 
Intrinsics  do  a  lazy  binding  of  the  error  database  and  do  not  merge  in  the  database  file  until  the 
first  call  to  XtAppGetErrorDatabaseText. 

Application-context-specific  error  handling  is  not  implemented  on  many  systems.  Most  imple 
mentations  will  have  just  one  set  of  error  handlers.  If  they  are  set  for  different  application 
contexts,  the  one  performed  last  will  prevail. 

The  high-level  error  and  warning  handler  procedure  pointers  are  of  type  xtErrorMsg- 
Handler.  For  a  complete  listing  of  all  errors  and  warnings  that  can  be  generated  by  the 
Intrinsics,  see  Appendix  D,  Standard  Errors  and  Warnings. 

Structures 

The  type  XrmDatabase  is  opaque  and  should  not  be  manipulated  directly.  The  return  value 
can  be  manipulated  with  the  Xlib  functions  XrmPutResource,  XrmQPutResource,  Xrm- 
GetResource,  and  XrmQGetResource. 

See  Also 

XtAppGetErrorDatabaseText(\\XtGetErrorDatabase(\\XtGetErrorDatabaseText(\), 
XtErrorMsgHandler(2). 
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XtAppGetErrorDatabaseText        \ 

v Xt  -  Error  Handling  — 

Name 

XtAppGetErrorDatabaseText  —  obtain  the  error  database  text  for  an  error  or  a  warning. 

Synopsis 

void  XtAppGetErrorDatabaseText (app_context,  name,  type,  class,  default, 

buffer_return,  nbytes,  database) 
XtAppContext  app_context; 
String  name,  type,  class; 
String  default; 
String  buffer_return; 
int  nbytes; 
XrmDatabase  database; 

Arguments 

app_ context      Specifies  the  application  context. 

name,  type          Specifies  the  name  and  type  that  are  concatenated  to  form  the  resource  name 
of  the  error  message. 

c i  a  ss  Specifies  the  resource  class  of  the  error  message. 

defaul  t  Specifies  the  default  message  to  use  if  an  error  database  entry  is  not  found. 

buffer_return  Specifies  the  buffer  into  which  the  error  message  is  to  be  returned. 
nbytes  Specifies  the  size  of  the  buffer  in  bytes. 

database  Specifies  the  name  of  the  alternative  database  to  be  used,  or  specifies  NULL  if 

the  application's  database  is  to  be  used.  r, 

Description 

Xt's  high-level  error  and  warning  message  handlers  use  a  resource-like  database  for  storing 
messages.  Messages  are  looked  up  by  name  and  class,  and  the  appropriate  message  retrieved 
from  the  database.  A  custom  error  message  handler  can  obtain  the  error  database  text  for  an 
error  or  a  warning  by  calling  XtAppGetErrorDatabaseText. 

XtAppGetErrorDatabaseText  returns  the  appropriate  message  from  the  error  database 
or  returns  the  specified  default  message  if  one  is  not  found  in  the  error  database. 

On  POSIX-based  systems,  the  error  database  is  usually  stored  in  lusrlliblXHIXtErrorDB.  Cus 
tom  error  or  warning  messages  should  be  appended  to  this  file. 

The  address  of  the  loaded  database  can  be  returned  by  a  call  to  xtAppGetErrorDatabase 
(or  xtGetErrorDat abase).  Note  that  application-context-specific  error  handling  is  not 
implemented  on  many  systems.  Most  implementations  will  have  just  one  set  of  error  handlers. 
If  they  are  set  for  different  application  contexts,  the  one  performed  last  will  prevail. 

Typical  usage  of  XtAppGetErrorDatabaseText  ()  is  deep  in  the  X  Toolkit  error  hand 
ling  code.  See  the  code  below  (slightly  modified  for  clarity)  for  use  of  this  function  from  the  Xt 
Intrinsics.  The  first  four  arguments  to  XtAppGetErrorDatabaseText  ( )  are  just  passed 
in  from  the  XtErrorMsg  ( )  call  in  XtMalloc  ( ) . 
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Xt- Error  Handling  (continued)  XtAppGetErrorDatabaseText 

The  xtMalloc  ( )  call  assumes  that  the  default  error  database  (errorDB)  has  an  error  mes 
sage  for  resource  name  allocError  .malloc  of  class  XtToolkitError.  If  not  found, 
the  default  error  message  "Cannot  perform  malloc"  will  be  used  instead. 

You  do  not  need  to  use  this  function  unless  you  are  writing  an  Xt  error  message  handler  of  your 
own. 

void 

XtErrorMsg(name,  type,  class,  defaultp,  params,  num_params) 

String  name,  type,  class,  defaultp; 

String*params; 

Cardinal *num_params; 

char  buffer [1000] ,  message [ 1000] ; 

XtGetErrorDatabaseText (name,  type,  class,  defaultp,  buffer,  1000); 

/* 

*  Need  better  solution  here,  perhaps  use  lower-level 

*  printf  primitives? 

*/ 

if  (num_jparams  ==  NULL) 

XtError (buffer) ; 

else  { 

(void)  sprintf (message,  buffer,  params [0],  params [1], 

params [2],  params [3],  params [4],  params [5], 

params [6],  params [7],  params [8],  params [9]); 

_XtDefaultError (message)  ; 


static  void 

_XtDefaultError (message) 
String  message; 

extern  void  exit(); 

(void) fprintf (stderr,  "X  Toolkit  Error:  %s\n",  message); 
exit (1) ; 

void 

XtGetErrorDatabaseText (name,  type,  class,  defaultp,  buffer,  nbytes) 

register  char*name,  *type,  *class; 

char* defaultp; 

char*buf fer; 

int  nbytes; 

XtAppGetErrorDatabaseText (_XtDefaultAppContext ()  , 
name,  type,  class,  defaultp,  buffer,  nbytes,  NULL); 
} 
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XtAppGetErrorDatabaseText  (continued)  Xt  -  Error  Handling 

See  Also 

XtAppGetErrorDatabase(l),  XtGetErrorDatabase(l),  XtGetErrorDatabaseText(\\ 
XtErrorMsgHandler(Z). 
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— Xt-  Selections- 


J  XtAppGetSelectionTlmeout 


Name 

XtAppGetSelectionTimeout  —  get  the  current  selection  timeout  value. 

Synopsis 

unsigned  int  XtAppGetSelectionTimeout (app_context) 
XtAppContext  app_context; 

Arguments 

app_cofltext      Specifies  the  application  context. 

Description 

XtAppGetSelectionTimeout  returns  the  current  selection  timeout  value  for  the  specified 
application  context,  in  milliseconds.  The  selection  timeout  is  the  time  within  which  the  two 
communicating  applications  must  respond  to  one  another.  The  initial  timeout  value  is  set  by 
the  selectionTimeout  application  resource,  or  if  selectionTimeout  is  not  specified, 
it  defaults  to  5000  milliseconds  (5  seconds).  A  new  value  can  be  set  by  a  call  to  xtAppSet- 
SelectionTimeout. 

See  Also 

XtAppSetSelectionTimeout  ( 1 ) 
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XtApplnitialize  \ 


•Xt -Initialization — 


Name 

XtApplnitialize  —  initialize  the  X  Toolkit  internals,  create  an  application  context,  open  a  dis 
play,  and  create  the  initial  application  shell  instance. 

Synopsis 

Widget  XtApplnitialize (app_context_return,  application_classf  options, 

num_options,  argc_in_out,  argv_in_out,  fallback_resources,  args, 
num_args) 

XtAppContext  * app_context_return; 

String  application_class; 

XrmOptionDescList  options; 

Cardinal  num_options; 

Cardinal  *argc_in_out; 

String  *argv_in_out; 

String  * fallback_resources; 

ArgList  args; 

Cardinal   num_args; 

Arguments 

app_context_return  Returns  the  application  context,  if  non-NULL. 

application_dass  Specifies  the  class  name  of  the  application. 

options  Specifies  the  command  line  options  table. 

num_  opt  ions  Specifies  the  number  of  entries  in  options. 

argc_in_out  Specifies  a  pointer  to  the  number  of  command  line  arguments. 

argv_in_out  Specifies  a  pointer  to  the  command  line  arguments. 

fallback_resources  Specifies  resource  values  to  be  used  if  the  application  class 

resource  file  cannot  be  opened  or  read,  or  NULL. 

args  Specifies  resource  values  to  override  any  other  resource  specifi 

cations  for  the  created  shell  widget. 

num_args  Specifies  the  count  of  args. 

Description 

XtApplnitialize  calls  XtToolkitlnitialize  and  XtCreateApplication- 
Context,  then  calls  XtOpenDisplay  with  a  display_  string  of  NULL  and  an  appli- 
cation_name  of  NULL,  and  finally  calls  xtAppCreateShell  with  an  applica- 
tion_name  of  NULL,  a  widget_class  of  applicationShellWidgetClass,  and  the 
specified  args  and  num_args  and  returns  the  created  shell.  The  modified  argc  and  argv 
returned  by  XtDisplaylnitialize  are  returned  in  argc_in_out  and  argv_in_out. 
If  app_context_return  is  not  NULL,  the  created  application  context  is  also  returned.  If 
the  display  specified  by  the  command  line  cannot  be  opened,  an  error  message  is  issued  and 
XtApplnitialize  terminates  the  application.  If  fallback_resources  is  non-NULL, 
XtAppSetFallbackResources  is  called  with  the  value  prior  to  calling  XtOpen 
Display. 
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Xt  -  Initialization  (continued)  XtApplnitialize 

The  XtNvisual  and  xtNcolormap  resources  must  be  set  while  creating  the  shell,  since 
they  are  permanent  characteristics  of  the  associated  window.  All  descendants  of  a  shell  inherit 
the  visual  and  colormap  of  the  shell. 

See  Also 

XtAppCreateShell(l),  XtAppSetFallbackResources(l),  XtCreateApplicationContext(l),  XtDisplay- 
Initialize(l),  XtOpenDisplay(l). 
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XtAppMainLoop  Yi 

v Xt  -  Event  Handling  — 

Name 

XtAppMainLoop  —  process  input  from  a  given  application. 

Synopsis 

void  XtAppMainLoop (app_context) 
XtAppContext  app_context; 

Arguments 

app_context      Specifies  the  application  context  that  identifies  the  application. 

Description 

XtAppMainLoop  first  reads  the  next  incoming  X  event  by  calling  xtAppNextEvent  and 
dispatches  it  to  the  appropriate  registered  procedure  by  calling  xtDispatchEvent.  This 
constitutes  the  main  loop  of  X  Toolkit  applications,  and  as  such,  it  does  not  return.  Applica 
tions  are  expected  to  exit  in  response  to  some  user  action. 

There  is  nothing  special  about  XtAppMainLoop;  it  is  simply  an  infinite  loop  that  calls  Xt 
AppNextEvent  and  then  XtDispatchEvent.  An  application  can  provide  its  own  version 
of  this  loop.  For  example,  it  might  test  an  application-dependent  global  flag  or  other  termina 
tion  condition  before  looping  back  and  calling  XtAppNextEvent.  For  example,  if  the  num 
ber  of  top-level  widgets  drops  to  zero,  the  application  may  be  able  to  exit  safely. 

See  XtAppAddWorkProc  for  information  on  how  to  spend  idle  time. 
See  Also 

XtAppAddWorkProc(\\  XtAppNextEvent  (I),  XtDispatchEvent(l). 
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Name 

XtAppNextEvent  —  return  next  event  from  an  application's  X  event  queue. 

Synopsis 

void  XtAppNextEvent (app_  con text,  event_return) 
XtAppContext  app_context; 
XEvent  *event_return; 

Arguments 

app_context  Specifies  the  application  context  that  identifies  the  application. 

event_return         Returns  the  event  information  from  the  dequeued  event  structure. 

Description 

If  a  server  has  queued  an  event  for  the  specified  application,  XtAppNextEvent  removes  the 
event  from  the  queue  and  returns  it  to  the  caller. 

If  there  are  no  events  in  the  X  input  queue,  XtAppNextEvent  flushes  the  X  output  buffers  of 
each  Display  in  the  application  context  and  waits  for  an  event  from  the  X  server  or  auxiliary 
input  sources  or  for  a  timeout  value  to  expire.  If  a  timer  pseudo-event  or  auxiliary  input  event 
occurs,  XtAppNextEvent  dispatches  the  designated  callbacks.  When  an  X  event  occurs, 
XtAppNextEvent  removes  it  from  the  queue  and  returns  it.  The  events  returned  by  XtApp 
NextEvent  should  be  dispatched  with  XtDispatchEvent.  XtAppNextEvent  dis 
patches  XtWorkProcs  and  XtTimerCallbackProcs  directly  that  are  registered  for 
app_context.  See  XtAppAddWorkProc  and  XtAppAddTimeOut. 

XtAppNextEvent  blocks  until  an  event  occurs.  An  application  can  instead  use  this  wait 
time  by  interleaving  background  processing  with  calls  to  XtAppPending. 

Programs  rarely  need  this  much  control  over  the  event  dispatching  mechanism.  Most  programs 
use  XtAppMainLoop. 

See  Also 

XtAppAddWorkProc  (I),  XtAppMainLoop  (I),  XtAppPeekEvent(\\  XtAppPending  (I),  XtAppProcess- 

Event(\\  XtDispatchEvent(\\ 

XtWorkProc(2). 
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Name 

XtAppPeekEvent  —  nondestructively  examine  the  head  of  an  application's  input  queue. 

Synopsis 

Boolean  XtAppPeekEvent (app_context,  event_return) 
XtAppContext  app_context; 
XEvent  * event_return; 

Arguments 

app_context      Specifies  the  application  context  that  identifies  the  application. 

event_return    Returns  the  event  information  from  the  head  event  structure  in  the  queue. 

Description 

XtAppPeekEvent  returns  the  value  from  the  head  of  a  given  application's  input  queue  with 
out  removing  input  from  the  queue. 

If  a  server  has  queued  an  event  for  the  application,  XtAppPeekEvent  fills  in  the  event  and 
returns  a  nonzero  value.  It  returns  True  if  the  event  returned  is  an  X  event  and  False  other 
wise  (i.e.,  if  it  is  a  Timer  or  alternate  input  event). 

If  there  is  an  event  in  the  queue,  XtAppPeekEvent  fills  in  the  event  and  returns  True.  If  no 
X  input  is  on  the  queue,  XtAppPeekEvent  flushes  the  output  buffers  of  each  Display  in  the 
application  context  and  blocks  until  input  is  available  (possibly  calling  some  timeout  callbacks 
in  the  process).  If  the  next  input  is  an  event,  XtAppPeekEvent  fills  in  the  event  and  returns 
True.  Otherwise,  the  input  is  for  an  alternate  input  source,  and  XtAppPeekEvent  returns 
False. 

Programs  rarely  need  this  much  control  over  the  event  dispatching  mechanism.  Most  programs 
use  XtAppMainLoop. 

However,  all  event  sources  depend  on  idle  time  in  the  application  to  return  to  XtAppMain 
Loop  where  Xt  can  check  to  see  if  input  is  available  from  any  of  the  various  sources.  If  an 
application  has  long  calculations  to  make,  the  program  may  not  return  to  XtAppMainLoop 
frequently  enough  to  detect  important  input  in  a  timely  fashion.  The  application  itself  should, 
if  possible,  suspend  important  calculations  for  a  moment  to  check  whether  input  is  available. 
Then  it  can  determine  whether  to  process  the  input  before  continuing  or  finish  the  calculation. 

To  detect  whether  input  from  any  input  source  is  available,  you  can  call  XtAppPending. 

To  find  out  what  the  first  event  in  the  queue  contains,  you  can  call  XtAppPeekEvent.  This 
function  returns  an  event  structure  without  removing  the  event  from  Xlib's  queue. 

It  is  also  possible  to  remove  and  process  a  single  event  xtAppProcessEvent  combines 
some  (but  not  all)  of  the  functions  from  XtAppNextEvent  and  XtDispatchEvent.  That 
is,  whereas  XtAppNextEvent  takes  the  next  event  from  the  queue — whatever  it  is,  XtApp 
ProcessEvent  allows  you  to  specify  as  a  mask  a  bitwise  OR  of  the  symbolic  constants  xt- 
IMXEvent,  XtlMTimer,  and  XtlMAlternatelnput.  This  lets  you  select  only  some  of 
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(continued) 


XtAppPeekEvent 


these  event  types  for  processing.   In  addition,  xtAppProcessEvent  actually  calls  xt- 
DispatchEvent  to  dispatch  X  events,  so  only  this  one  call  is  necessary. 

See  Also 

XtAppMainLoop(l),  XtAppNextEvent(l),  XtAppPending(l),  XtAppProcessEvent (1),  XtDispatchEvent(\). 
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Name 

XtAppPending  —  determine  whether  any  events  are  in  an  application's  input  queue. 

Synopsis 

XtlnputMask  XtAppPending (app_context) 
XtAppContext  app_ con text; 

Arguments 

app_context      Specifies  the  application  context  for  the  application  to  check. 

Description 

XtAppPending  returns  a  nonzero  value  if  there  are  pending  events  from  the  X  server,  timer, 
or  other  input  sources.  The  return  value  is  a  bit  mask  that  is  the  OR  of  xtlMXEvent  (an  X 
event),  xtlMTimer  (a  timer  event  introduced  onto  the  queue  by  a  call  to  xtAppAddTime- 
Out),  and  xtlMAlternatelnput  (an  alternate  input  event  introduced  onto  the  queue  by  a 
call  to  xtAppAddlnput).  As  a  convenience,  the  symbolic  name  xtlMAll  is  defined  as  the 
bitwise  inclusive  OR  of  all  event  types.  If  no  events  are  pending,  XtAppPending  flushes  the 
output  buffers  of  each  display  in  the  application  context  and  returns  zero.  This  call  is  the 
Intrinsics  equivalent  to  the  Xlib  call  XPending. 

Programs  rarely  need  this  much  control  over  the  event  dispatching  mechanism.  Most  programs 
use  XtAppMainLoop. 

However,  all  event  sources  depend  on  idle  time  in  the  application  to  return  XtAppMainLoop 
where  Xt  can  check  to  see  if  input  is  available  from  any  of  the  various  sources.  If  an  applica 
tion  has  long  calculations  to  make,  the  program  may  not  return  to  XtAppMainLoop  fre 
quently  enough  to  detect  important  input  in  a  timely  fashion.  The  application  itself  should,  if 
possible,  suspend  important  calculations  for  a  moment  to  check  whether  input  is  available. 
Then  it  can  determine  whether  to  process  the  input  before  continuing  or  finish  the  calculation. 

To  detect  whether  input  from  any  input  source  is  available,  you  can  call  XtPending. 

To  find  out  what  the  first  event  in  the  queue  contains,  you  can  call  XtAppPeekEvent.  This 
function  returns  an  event  structure  without  removing  the  event  from  Xlib's  queue. 

It  is  also  possible  to  remove  and  process  a  single  event.  xtAppProcessEvent  combines 
some  (but  not  all)  of  the  functions  from  XtAppNextEvent  and  XtDispatchEvent.  That 
is,  while  XtAppNextEvent  takes  the  next  event  from  the  queue,  whatever  it  is,  XtApp 
ProcessEvent  allows  you  to  specify  as  a  mask  a  bitwise  OR  of  the  symbolic  constants  xt- 
IMXEvent,  XtlMTimer,  and  XtlMAlternatelnput.  This  lets  you  select  only  some  of 
these  event  types  for  processing.  In  addition,  XtAppProcessEvent  actually  calls  Xt 
DispatchEvent  to  dispatch  X  events,  so  only  this  one  call  is  necessary. 

See  Also 

XtAppAddlnput^),  XtAppAddTimeOut(l),  XtAppMainLoop  (1),  XtAppNextEvent(l),  XtAppPeekEvent  (I), 
XtAppProcessEvent(l),  XtDispatchEvent(l ). 
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Name 

XtAppProcessEvent  —  process  one  input  event 

Synopsis 

void  XtAppProcessEvent (app_context,  mask) 
XtAppContext  app_context; 
XtlnputMask  mask; 

Arguments 

app_context      Specifies  the  application  context  for  which  to  process  input. 

mask  Specifies  what  types  of  events  to  process.  The  mask  is  the  bitwise  inclusive 

OR  of  XtlMXEvent  (X  event),  xtlMTimer  (timer  events),  or  xt- 
IMAlternatelnput  (alternate  input  events).  The  symbolic  name  xt- 
IMA11  is  the  bitwise  inclusive  OR  of  all  event  types. 

Description 

While  most  widgets  will  use  the  Resource  Manager  to  handle  events,  the  X  Toolkit  does  pro 
vide  a  mechanism  for  widgets  or  application  code  to  handle  X  events  directly.  Every  client 
interested  in  X  events  on  a  widget  uses  xtAddEventHandler  to  register  which  events  it  is 
interested  in  and  a  procedure  (event  handler)  that  is  to  be  called  when  the  event  happens  in  that 
window.  The  handler  can  then  use  XtAppProcessEvent  to  actually  handle  the  events. 
XtAppProcessEvent  processes  an  X  event,  a  timer  event,  or  an  alternate  input  event.  If 
there  is  nothing  to  process,  XtAppProcessEvent  blocks  until  there  is.  If  there  is  more  than 
one  type  of  event  available,  the  one  that  will  get  processed  is  undefined. 

XtAppProcessEvent  processes  timer  events  and  alternate  input  events  by  calling  the 
appropriate  callbacks,  the  same  way  xtAppPeekEvent  and  xtAppNextEvent  do.  Xt 
AppProcessEvent  calls  xtDispatchEvent  to  handle  X  events. 

When  an  X  event  is  received,  it  is  passed  to  XtDispatchEvent,  which  calls  the  appropriate 
event  handlers  and  passes  them  the  widget,  the  event,  and  client-specific  data  registered  with 
each  procedure.  If  there  are  no  handlers  registered  for  that  event,  the  event  is  ignored  and  the 
dispatcher  simply  returns.  The  order  in  which  the  handlers  are  called  is  undefined. 

Programs  rarely  need  this  much  control  over  the  event  dispatching  mechanism.  Most  programs 
use  XtAppMainLoop. 

See  Also 

XtAppMainLoop (1),  XtAppNextEvent(\\  XtAppPeekEvent(\\  XtAppPending(l),  XtDispatchEvent(\). 
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v Xt  -  Resource  Management — 

Name 

XtAppReleaseCacheRefs  —  explicitly  decrement  the  reference  counts  for  cached  resources 

obtained  from  XtCallConverter. 

Synopsis 

void  XtAppReleaseCacheRef s (app,  refs) 
XtAppContext  app; 
XtCacheRef  *refs; 

Arguments 

app  Specifies  the  application  context. 

refs  Specifies  the  list  of  cache  references  to  be  decremented. 

Description 

XtAppReleaseCacheRefs  decrements  the  reference  count  for  the  conversion  entries  iden 
tified  by  the  refs  argument  refs  is  a  pointer  to  a  NULL-terminated  list  of  XtCacheRef 
values.  If  any  reference  count  reaches  zero,  the  destructor  registered  with  xt Set Type - 
Converter,  if  any,  will  be  called  and  the  resource  removed  from  the  conversion  cache. 

See  Also 

XtCollbackReleaseCacheRef(\ ),  XtCallbackReleaseCacheRe}List(\),  XtSefTypeConverter ( 1 ), 
XtDestructor(T). 
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Name 

XtAppSetErrorHandler  —  register  a  procedure  to  be  called  on  fatal  error  conditions. 

Synopsis 

XtErrorHandler  XtAppSetErrorHandler (app_context,  handler) 
XtAppContext  app_context; 
XtErrorHandler  handler; 

Arguments 

app_context      Specifies  the  application  context. 

handler  Specifies  the  new  fatal  error  procedure,  which  should  not  return. 

Description 

XtAppSetErrorHandler  returns  a  pointer  to  the  previously  installed  low-level  fatal  error 
handler.  The  default  low-level  error  handler  provided  by  the  Intrinsics  is  _xtDefault- 
Error.  On  POSIX-based  systems,  it  prints  the  message  to  standard  error  and  terminates  the 
application. 

Using  XtAppSetErrorHandler  or  XtSetErrorHandler,  you  can  replace  this  default 
handler  with  one  of  your  own. 

Fatal  error  handlers  should  not  return.  If  one  does,  subsequent  X  Toolkit  behavior  is  undefined. 

Note  that  application-context-specific  error  handling  is  not  implemented  on  many  systems. 
Most  implementations  will  have  just  one  set  of  error  handlers.  If  they  are  set  for  different 
application  contexts,  the  one  performed  last  will  prevail. 

See  Also 

XtAppError(\\  XtAppErrorMsg(\\  XtAppSetErrorMsgHondler(\),  XtAppSetWorningHandler(l\  Xt- 

AppSetWarningMsgHandler(l),  XtAppWarning(l),  XtAppWarningMsg(l), 

XtErrorHandler(T). 
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v Xt  -  Error  Handling— 

Name 

XtAppSetErrorMsgHandler  —  register  a  procedure  to  be  called  on  fatal  error  conditions. 

Synopsis 

XtErrorMsgHandler  XtAppSetErrorMsgHandler (app_ con  text,  msg_handler) 
XtAppContext  app_context; 
XtErrorMsgHandler  msg_handler; 

Arguments 

app_context      Specifies  the  application  context. 

msg_handler     Specifies  the  new  fatal  error  message  handling  procedure,  which  should  not 
return. 

Description 

XtAppSetErrorMsgHandler  returns  a  pointer  to  the  previously  installed  high-level  fatal 
error  handler.  The  default  high-level  fatal  error  handler  provided  by  the  Intrinsics  is  named 
_xtDef  aultErrorMsg.  This  fatal  error  handler  constructs  a  string  from  the  error  resource 
database  (see  XtAppGetErrorDatabase)  and  calls  xtError. 

Using  XtAppSetErrorMsgHandler,  you  can  replace  the  default  handler  with  one  of  your 
own.  Note  that  if  you  simply  want  to  change  the  way  the  message  is  displayed  (rather  than  the 
way  the  message  database  is  used),  you  should  probably  replace  the  low-level  error  handler 
(using  XtAppSetErrorHandler)  instead. 

Fatal  error  message  handlers  should  not  return.  If  one  does,  subsequent  X  Toolkit  behavior  is 
undefined.  See  xtErrorMsgHandler(2)  for  details.  Note  that  application-context-specific 
error  handling  is  not  implemented  on  many  systems.  Most  implementations  will  have  just  one 
set  of  error  handlers.  If  they  are  set  for  different  application  contexts,  the  one  performed  last 
will  prevail. 

See  Also 

XtAppError(\\  XtAppErrorMsg(\\  XtAppSetErrorHandler (\\  XtAppSetWarningHandler(\\  XtAppSet- 
WarningMsgHandler(\),  XtAppWarning(V),  XtAppWarningMsg(l), 
XtErrorHandler  (2),  XtErrorMsgHandler  (2). 
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Name 

XtAppSetFallbackResources  —  specify  a  default  set  of  resource  values. 

Synopsis 

void  XtAppSetFallbackResources (app_context,  specification_list) 
XtAppContext  app_context; 
String  *  sped  float  ion_list; 

Arguments 

app_context  Specifies  the  application  context  in  which  the  fallback  specifications  will 

be  used. 

sped  float  ion_l  1st 

Specifies  a  NULL-terminated  list  of  resource  specifications  to  pre-load  the 
database,  or  NULL. 

Description 

XtAppSetFallbackResources  specifies  a  default  set  of  resource  values  that  will  be  used 
to  initialize  the  resource  database  if  no  application-specific  class  resource  file  is  found  (the 
app-de faults  file). 

Each  entry  in  specif ication_list  points  to  a  string  in  the  format  of  XrmPutLine- 
Resource.  In  the  future,  if  XtDisplaylnitialize  is  not  able  to  find  or  read  an  applica 
tion-specific  class  resource  file  according  to  the  rules  given  above,  and  if  specif ica- 
tion_list  is  non-NULL,  then  the  display-specific  resource  database  will  be  initialized  with 
the  resource  specifications  in  specif  ication_list. 

XtAppSetFallbackResources  is  not  required  to  copy  specif ication_list\  the 
caller  must  ensure  that  the  contents  of  the  list  and  of  the  strings  addressed  by  the  list  remain 
valid  until  all  displays  are  initialized,  or  until  XtAppSetFallbackResources  is  called 
again. 

The  value  NULL  for  specif 'ication_list  removes  any  previous  fallback  resource  specifi 
cation  for  the  application  context.  The  intended  use  is  to  provide  a  minimal  number  of 
resources  that  make  the  application  usable  (or  at  least  terminate  with  helpful  diagnostic  mes 
sages)  when  some  problem  exists  in  finding  and  loading  the  application-defaults  file. 

xtApplnitialize  provides  an  argument  for  specifying  the  fallback  resources,  so  few  appli 
cations  need  to  call  XtAppSetFallbackResources  directly. 

See  Also 

XtAppInitiolize(l),  XtDisplayInitialize(l),  XtOpenDisplay(\). 
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•Xt- Selections— 


Name 

XtAppSetSelectionTimeout  —  set  the  Intrinsics  selection  timeout 

Synopsis 

void  XtAppSetSelectionTimeout (app_context,  timeout) 
XtAppContext  app_context; 
unsigned  long  timeout; 

Arguments 

app_context      Specifies  the  application  context. 

timeout  Specifies  the  selection  timeout  in  milliseconds. 

Description 

XtAppSetSelectionTimeout  sets  the  Intrinsics  selection  timeout  value  for  the  specified 
application  context.  The  selection  timeout  is  the  time  within  which  the  two  communicating 
applications  must  respond  to  one  another.  The  initial  timeout  value  is  set  by  the  selection- 
Timeout  application  resource,  or  if  selectionTimeout  is  not  specified,  it  defaults  to 
5000  milliseconds  (5  seconds). 

The  current  timeout  value  can  be  retrieved  by  a  call  to  XtAppGetSelectionTimeout. 
See  Also 

XtAppGetSelectionTimeout  ( 1 ) 
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Name 


XtAppSetTypeConverter 


XtAppSetTypeConverter  —  register  a  type  converter  in  a  single  application  context. 
Synopsis 

void  XtAppSetTypeConverter (app_context,  from_type,  to_type,  converter, 

convert_args,  num_args,  cache_type,  destructor) 
XtAppContext  app_context 
String  from_type; 
String  tq_type; 
XtTypeConverter  converter; 
XtConvertArgList  convert_args; 
Cardinal  num_args; 
XtCacheType  cache_type; 
XtDestructor  destructor; 


Arguments 

app_context 

from_type 

to_type 

converter 

convert_args 

num_args 

cache_type 

destructor 


Specifies  the  application  context. 

Specifies  the  source  type. 

Specifies  the  destination  type. 

Specifies  the  resource  type  converter  procedure. 

Specifies  additional  conversion  arguments,  or  NULL. 

Specifies  the  count  of  additional  conversion  arguments,  or  zero. 

Specifies  whether  or  not  resources  produced  by  this  converter  are  sharable  or 
display-specific  and  when  they  should  be  freed. 

Specifies  a  destroy  procedure  for  resources  produced  by  this  conversion,  or 
NULL  if  no  additional  action  is  required,  to  deallocate  resources  produced  by 
converter. 


Description 

XtAppSetTypeConverter  registers  the  specified  type  converter  in  the  single  application 
context  specified.  If  the  same  from_type  and  to_type  are  specified  in  multiple  calls  to 
either  function,  the  most  recent  overrides  the  previous  ones.  Similarly,  Xt  Set  Type  - 
Converter  registers  the  specified  type  converter  and  destructor  in  all  application  contexts 
created  by  the  calling  process,  including  any  future  application  contexts  which  may  be  created. 

See  Also 

XtAppReleoseCacheRefs(\\  XtCallbackReleaseCacheRef(l),  XtCallbackReleaseCacheRejList(\\  Xt- 
CallConverter(\\  XtConvertAndStore(l),  XtSe(TypeConverter(\\ 
XffypeConverter  (2),  XtDestructor  (2). 
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XtAppSetWarningHandler  \ 

v Xt-  Error  Handling  — 

Name 

XtAppSetWarningHandler  —  register  a  procedure  to  be  called  on  nonfatal  error  conditions. 

Synopsis 

XtErrorHandler  XtAppSetWarningHandler (app_context,  handler) 
XtAppContext  app_context; 
XtErrorHandler  handler; 

Arguments 

app_context      Specifies  the  application  context. 

handler  Specifies  the  new  nonfatal  error  procedure,  which  usually  returns. 

Description 

XtAppSetWarningHandler  returns  a  pointer  to  the  previously  installed  low-level  warning 
handler.  The  default  low-level  warning  handler  provided  by  the  Intrinsics  is  _xtDef ault- 
Warning.  On  POSIX-based  systems,  it  prints  the  message  to  standard  error  and  returns  to  the 
caller.  Using  XtAppSetWarningHandler,  you  can  replace  this  default  handler  with  one  of 
your  own. 

Note  that  application-context-specific  error  handling  is  not  implemented  on  many  systems. 
Most  implementations  will  have  just  one  set  of  error  handlers.  If  they  are  set  for  different 
application  contexts,  the  one  performed  last  will  prevail. 

See  Also 

XtAppError(\\  XtAppErrorMsg(\),  XtAppSetError Handler (1),  XtAppSetErrorMsgHandler(\\  XtApp 
SetWarningHandler  (\\  XtAppSetWarningMsgHandler(\\  XtAppWarning(\),  XtAppWarningMsg(l), 
XtErrorHandler  (2). 
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J       XtAppSetWarningMsgHandler 


Name 

XtAppSetWarningMsgHandler  —  register  a  procedure  to  be  called  on  nonfatal  error  condi 
tions. 

Synopsis 

XtErrorMsgHandler  XtAppSetWarningMsgHandler (app_context,  msg_handler) 
XtAppContext  app_context; 
XtErrorMsgHandler  msg_handler; 

Arguments 

app__context      Specifies  the  application  context. 

msg_handler      Specifies  the  new  nonfatal  error  procedure,  which  usually  returns. 

Description 

XtAppSetWarningMsgHandler  returns  a  pointer  to  the  previously  installed  high-level 
warning  handler.  The  default  high-level  warning  handler  provided  by  the  Intrinsics  is  named 
_XtDef  aultWarningMsg  and  constructs  a  string  from  the  error  resource  database  and  calls 
XtWarning.  Using  XtAppSetWarningMsgHandler,  you  can  replace  this  default  handler 
with  one  of  your  own.  Note  that  if  you  simply  want  to  change  the  way  the  message  is  displayed 
(rather  than  the  way  the  message  database  is  used),  you  should  probably  replace  the  low-level 
warning  handler  (using  xtAppSetWarningHandler)  instead. 

Note  that  application-context-specific  error  handling  is  not  implemented  on  many  systems. 
Most  implementations  will  have  just  one  set  of  error  handlers.  If  they  are  set  for  different 
application  contexts,  the  one  performed  last  will  prevail. 

See  Also 

XtAppError(\),  XtAppErrorMsg(\\  XtAppSetErrorHandler(\\  XtAppSetErrorMsgHandler(\),  XtApp- 
SetWarningHandler(l),  XtAppSetWarningMsgHandler(\),  XtAppWarning(\),  XtAppWarningMsg(l), 
XtErrorHandler(2\XtErrorMsgHandler(2). 
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XtAppWarning  \ 

v Xt  -  Error  Handling  — 

Name 

XtAppWarning  —  call  the  installed  nonfatal  error  procedure. 

Synopsis 

void  XtAppWarning (app_con text,  message) 
XtAppContext  app_context; 
String  message; 

Arguments 

app_  con  text      Specifies  the  application  context. 

message  Specifies  the  nonfatal  error  message  that  is  to  be  reported. 

Description 

Xt  provides  two  levels  of  error  handling: 

•  A  high-level  interface  that  takes  an  error  name  and  class  and  looks  the  error  up  in  an 
error  resource  database. 

•  A  low-level  interface  that  takes  a  simple  string,  which  is  printed  out  as  the  error  message. 

Application-context-specific  error  handling  is  not  implemented  on  many  systems.  Most  imple 
mentations  will  have  just  one  set  of  error  handlers.  If  different  handlers  are  set  for  different 
application  contexts,  the  one  set  last  will  be  used. 

In  theory,  most  programs  should  use  XtAppWarningMsg,  not  XtAppWarning,  so  that  pro 
grams  can  be  easily  customized  to  provide  international  or  other  custom  error  messages.  How 
ever,  the  low-level  handlers  are  much  easier  to  use. 

xtAppError  calls  the  low-level  fatal  error  handler.  Fatal  errors  are  assumed  to  be  catastro 
phic  and  irrecoverable.  A  warning  error  handler  also  exists  for  errors  that  require  attention  but 
do  not  preempt  a  program  running  correctly  to  a  normal  successful  completion.  (XtApp 
Warning  calls  the  corresponding  non-fatal  error  handler.  XtAppErrorMsg  and  XtApp 
WarningMsg  call  the  corresponding  high-level  handlers.) 

See  Also 

XtAppError  (I),  XtAppErrorMsg  (1),  XtAppSetErrorHandler(\\  XtAppSetErrorMsgHandler(\\  XtApp- 
SetWarningHandler  ( 1 ),  XtAppSetWarningMsgHandler  ( 1 ),  XtAppWarningMsg  ( 1 ), 
XtErr or Handler  (2),  XtErrorMsgHandler  (2). 
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/  XtAppWarningMsg 

— Xt  -  Error  Handling ' 

Name 

XtAppWarningMsg  —  call  the  installed  high-level  warning  handler. 

Synopsis 

void  XtAppWarningMsg (app_context,  name,  type,  class  ,  default,  params, 

num_params) 

XtAppContext  app_context; 
String  name; 
String  type; 
String  class; 
String  default; 
String  *params; 
Cardinal  *num_params; 

Arguments 

app_ context      Specifies  the  application  context. 

name  Specifies  the  general  kind  of  error;  for  example,  invalidParameter. 

type  Specifies  the  detailed  name  of  the  error.  This  is  specified  using  printf-like 

syntax,  with  the  parameters  and  number  of  parameters  specified  by  params 
and  num_params. 

class  Specifies  the  resource  class. 

defaul  t  Specifies  the  default  message  to  use  if  no  message  is  found  in  the  database. 

params  Specifies  a  pointer  to  a  list  of  values  to  be  stored  in  the  type  argument  when 

the  message  if  generated. 

numjparams       Specifies  the  number  of  values  in  the  parameter  list. 

Description 

Xt  provides  two  levels  of  error  handling: 

•  A  high-level  interface  that  takes  an  error  name  and  class  and  looks  the  error  up  in  an 
error  resource  database. 

•  A  low-level  interface  that  takes  a  simple  string,  which  is  printed  out  as  the  error  message. 

The  high-level  functions  construct  a  string  to  pass  to  the  lower-level  interface.  The  name  and 
type  arguments  are  concatenated  to  form  the  "name"  that  is  used  to  look  up  a  message  in  the 
error  database.  On  POSIX-based  systems,  the  error  database  is  usually  lusrlliblXlllXtErrorDB. 
In  theory,  most  programs  should  use  xtAppErrorMsg  (or  xtErrorMsg  if  application 
contexts  are  not  being  used),  not  xtAppError  or  xtError,  so  that  the  programs  can  be  eas 
ily  customized  to  provide  international  or  other  custom  error  messages.  However,  the  low-level 
handlers  are  much  easier  to  use. 

XtAppError  calls  the  low  level  fatal  error  handler.  Fatal  errors  are  assumed  to  be  catastro 
phic  and  irrecoverable.  A  warning  error  handler  also  exists  for  errors  that  require  attention  but 
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do  not  preempt  a  program  running  correctly  to  a  normal  successful  completion.  (xtApp- 
Warning  calls  the  corresponding  non-fatal  error  handler.  xtAppErrorMsg  and  xtApp- 
WarningMsg  call  the  corresponding  high-level  handlers.) 

See  Also 

XtAppError(\\  XtAppErrorMsg(\),  XtAppSetErr or Handler (1),  XtAppSetErrorMsgHandler(\\  XtApp- 

SetWarningHandler(\),XtAppSetWarningMsgHandIer(l),XtAppWarning(\), 

XtError Handler  (2),  XtErrorMsgHandler  (2). 
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— Xt  -  Translations  and  Actions- 


XtAugmentTranslations 


Name 

XtAugmentTranslations  —  nondestructively  merge  new  translations  with  widget's  existing 

ones. 

Synopsis 

void  XtAugmentTranslations (w,  translations) 
Widget  w; 
XtTranslations  translations; 

Arguments 

w  Specifies  the  widget  into  which  the  new  translations  are  to  be  merged. 

translations         Specifies  the  compiled  translation  table  to  merge  in  (must  not  be  NULL). 
Description 

XtAugmentTranslations  nondestructively  merges  translations  into  a  widget's 
existing  translations,  ignoring  any  # replace,  #augment,or  ^override  directive  that  may 
have  been  specified  in  the  translation  string.  If  translations  contains  an  event  or  event 
sequence  that  already  exists  in  the  widget's  translations,  then  the  new  translation  is  ignored. 

The  translation  table  must  be  in  compiled  form,  as  produced  by  xtParseTranslation- 
Table. 

Translation  tables  can  also  be  constructed  by  converting  resources.  To  make  it  easy  to  modify 
translation  tables  in  resource  files,  the  string-to-translation-table  resource  type  converter  allows 
you  to  specify  whether  the  table  should  replace,  augment,  or  override  any  existing  translation 
table  in  the  widget  As  an  option,  a  pound  sign  (#)  as  the  first  character  of  the  table  followed  by 
replace  (default),  augment,  or  override  indicates  how  to  treat  existing  translations. 

The  replace  or  merge  operation  is  performed  during  the  Core  instance  initialization  and  during 
the  Core  set_values  invocation.  At  instance  initialization  the  widget  class  translation  table 
(if  any)  is  copied  into  the  widget  prior  to  a  merge  operation.  The  merge  operation  produces  a 
new  translation  resource  value;  if  the  original  table  was  shared  by  other  widgets,  they  are  unaf 
fected. 

To  merge  new  translations  but  keep  existing  translations  in  case  of  conflict,  use  XtAugment 
Translations.  To  completely  remove  existing  translations,  use  XtUninstall- 
Translations. 

XtParseTranslationTable  produces  the  binary  form  of  the  translation  table  from  text. 
XtConvert  can  also  do  the  conversion,  specifying  xtRTranslationTable  as  the  desti 
nation  resource  type.  A  text  translation  table  is  automatically  parsed  in  the  Core  widget  struc 
ture  when  a  widget  class  is  initialized. 

See  Also 

XtConvertAndStore(\\  XtOverrideTranslations(l),  XtParseTranslationTable  (I),  XtUninstall- 
Translations  ( 1 ). 
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XtBuildEventMask 


X 


•  Xt-  Event  Handling— 


Name 

XtBuildEventMask  —  retrieve  a  widget's  event  mask. 

Synopsis 

EventMask  XtBuildEventMask (w) 
Widget  w; 


Arguments 


Specifies  the  widget 


Description 

XtBuildEventMask  returns  a  widget's  event  mask.  The  mask  reflects  the  events  the  widget 
is  currently  selecting.  (If  the  widget  is  unrealized,  then  the  mask  reflects  the  events  the  widget 
will  select  when  it  is  realized.)  This  event  mask  is  the  logical  OR  of  all  event  masks  selected 
by  adding  event  handlers  and  event  translations  (including  accelerators). 

This  event  mask  is  stored  in  the  XSetWindowAt tributes  structure  by  XtRealize- 
widget  and  is  sent  to  the  server  when  event  handlers  and  translations  are  installed  or  removed 
for  the  realized  widget 

Structures 

The  event_mask  is  formed  by  combining  the  event  mask  symbols  listed  in  the  first  column  of 
the  table  below  using  the  bitwise  OR  operator  (|).  Each  mask  symbol  sets  a  bit  in  the 

event_mask. 

The  table  also  briefly  describes  the  circumstances  under  which  you  would  want  to  specify  each 
symbol. 


Event  Mask  Symbol 


NoEventMask 

KeyPressMask 

KeyReleaseMask 

Button? re ssMask 

ButtonReleaseMask 

EnterWindowMask 

LeaveWindowMask 

PointerMotionMask 

Point erMotionHintMask 

ButtonlMotionMask 

Button2MotionMask 

Button3MotionMask 

ButtonlMotionMask 

ButtonSMotionMask 

ButtonMotionMask 

KeymapStateMask 


Circumstances 


No  events 

Keyboard  down  events 

Keyboard  up  events 

Pointer  button  down  events 

Pointer  button  up  events 

Pointer  window  entry  events 

Pointer  window  leave  events 

All  pointer  motion  events 

Fewer  pointer  motion  events 

Pointer  motion  while  button  1  down 

Pointer  motion  while  button  2  down 

Pointer  motion  while  button  3  down 

Pointer  motion  while  button  4  down 

Pointer  motion  while  button  5  down 

Pointer  motion  while  any  button  down 

Any  keyboard  state  change  on  EnterNotif  y, 

LeaveNotif y, Focusln  or  FocusOut 
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Event  Mask  Symbol 


ExposureMask 

VisibilityChangeMask 

StructureNotifyMask 

ResizeRedirectMask 

SubstructureNotifyMask 

SubstructureRedirectMask 

FocusChangeMask 

Property ChangeMask 

ColormapChangeMask 

OwnerGrabButtonMask 


(continued) 


Circumstances 


XtBuildEventMask 


Any  exposure  (except  GraphicsExpose  and 

NoExpose) 

Any  change  in  visibility 

Any  change  in  window  configuration. 

Redirect  resize  of  this  window 

Notify  about  reconfiguration  of  children 

Redirect  reconfiguration  of  children 

Any  change  in  keyboard  focus 

Any  change  in  property 

Any  change  in  colormap 

Modifies  handling  of  pointer  events 


See  Also 

XtAddEventHandler(\\  XtAddRawEventHandler(\\  XtReaHzeWidget(l). 
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XtCallAcceptFocus  \  _ 

v  -  Xt  -  Keyboard  Handling  — 

Name 

XtCallAcceptFocus  —  call  a  widget's  accept_f  ocus  procedure. 

Synopsis 

Boolean  XtCallAcceptFocus  (w,  time) 
Widget  w; 
Time  *time; 

Arguments 

w  Specifies  the  widget. 

time  Specifies  the  X  time  of  the  event  that  is  causing  the  accept  focus. 

Description 

XtCallAcceptFocus  calls  the  specified  widget's  accept_f  ocus  method,  passing  it  the 
specified  widget  and  time,  and  returns  whatever  the  accept_f  ocus  method  returns.  If  the 

accept_focus  method  is  NULL,  XtCallAcceptFocus  returns  False. 

XtCallAcceptFocus  does  not  actually  set  the  keyboard  focus;  it  is  used  to  determine  if  the 
widget  would  take  the  focus  if  offered.  xtSetKeyboardFocus  and  the  Xlib  function 
xsetlnputFocus  actually  pass  the  focus  to  a  child. 

The  accept_f  ocus  method  is  part  of  the  Core  class  structure. 
See  Also 

XtSetKeyboardFocus(\), 


accept  Jocus  (4). 
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.  XtCallActionProc 

— Xt  -  Translations  and  Actions ' 

Name 

XtCallActionProc  —  invoke  an  action  procedure  without  generating  events. 

Synopsis 

void  XtCallActionProc (widget,  action,  event,  params,  num_params) 
Widget  widget; 
String  action; 
XEvent  * event; 
String  *para/ns; 
Cardinal  num_params; 

Arguments 

widget  Specifies  the  widget  in  which  the  action  is  to  be  invoked. 

action  Specifies  the  name  of  the  action  routine. 

event  Specifies  the  contents  of  the  event  argument  passed  to  the  action  routine. 

params  Specifies  the  contents  of  the  params  argument  passed  to  the  action  routine. 

numjparams  Specifies  the  count  of  entries  in  the  pa  rams  list. 

Description 

XtCallActionProc  searches  for  the  named  action  routine  in  the  same  manner  and  order  as 
translation  tables  are  bound,  except  that  application  action  tables  are  searched,  if  necessary,  as 
of  the  time  of  the  call  to  XtCallActionProc.  If  found,  the  action  routine  is  invoked  with 
the  specified  widget,  event  pointer  and  parameters.  It  is  the  responsibility  of  the  caller  to 
ensure  that  the  contents  of  the  event,  params  and  num_params  arguments  are  appropriate 
for  the  specified  action  routine  and,  if  necessary,  that  the  specified  widget  is  realized  and/or 
sensitive.  If  the  named  action  routine  cannot  be  found,  XtCallActionProc  generates  a 
warning  message  and  returns. 

See  Also 

XtAppAddActionHook(l),XtRemoveActionHook(l), 
XtActionHookProc  (2). 
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XtCallbackExclusive 


X 


•Xt-PopUps— 


Name 

XtCallbackExclusive  —  callback  function  to  pop  up  a  widget 

Synopsis 

void  XtCallbackExclusive ( w,  client_data,  call_data) 
Widget  w; 

XtPointer  client_data; 
XtPointer  call_data; 

Arguments 

w  Specifies  the  widget 

client_data      Specifies  the  pop-up  shell. 

call_data         Specifies  the  callback  data,  which  is  not  used  by  this  procedure. 

Description 

The  functions  XtCallbackNone,  XtCallbackNonexclusive,  and  XtCallback 
Exclusive  are  built-in  callback  functions  that  call  xtPopup.  You  can  register  any  of  these 
callback  functions  in  a  callback  list.  The  pop-up  shell  is  specified  by  the  clie/it_data  argu 
ment  of  the  callback  function,  and  the  grab_kind  argument  of  XtPopup  is  set  according  to 
the  name  of  the  callback  function: 

•  XtCallbackNone  specifies  XtGrabNone. 

•  XtCallbackNonexclusive  specifies  XtGrabNonexclusive. 

•  XtCallbackExclusive  specifies  XtGrabExclusive. 

Each  of  these  callback  functions  then  sets  the  widget  that  executed  the  callback  list  to  be  insen 
sitive  by  using  XtSetSensitive. 

These  callback  functions  provide  one  strategy  for  popping  up  widgets — but  you  are  not 
required  to  use  them.  The  built-in  action  XtMenuPopup  can  be  used  for  some  pop  ups.  An 
application  may  provide  customized  code  to  create  pop-up  shells  dynamically  or  that  must  do 
more  than  desensitizing  the  button. 

For  example,  XtCallbackExclusive  does  nothing  to  place  the  pop-up  widget  so  it  pops 
up  in  the  upper-left  corner  of  the  display.  A  custom  pop-up  routine  might  move  the  pop-up 
shell  to  the  location  of  the  pointer,  or  the  middle  of  the  current  window,  before  calling  Xt 
Popup.  This  can  also  be  done  in  a  separate  callback  function,  added  to  the  callback  list  before 

XtCallback*. 

An  example  follows: 


f  () 

{ 


Widget  pshell,  button; 


pshell  =  XtCreatePopupShell ( . . . ) 
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button  =  XtCreateWidget (...); 

XtAddCallback (button, XtNcallback, XtCallbackNone,pshell) ; 
} 

When  the  widget  invokes  XtCallCallbacks  on  its  XtNcallback  resource,  the  pop-up 
shell  p she  11  will  be  popped  up. 

A  companion  example  to  the  one  above  is  presented  on  the  xtCallbackPopdown  reference 
page. 

See  Also 

XtCallbackNone(\\  XtCallbackPopdown(\\  XtCallCallbacks(l),  XtMoveWidget(\\  XtPopdown(l\  Xt- 
Popup(l),  XtSetSensitive(\). 
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XtCallbackNone 

Xt  -  Pop  Ups— 

Name 

XtCallbackNone  —  callback  function  to  pop  up  a  widget 

Synopsis 

void  XtCallbackNone (wr  client_data,  call_data) 
Widget  w; 

XtPointer  client_data; 
XtPointer  call_data; 

Arguments 

w  Specifies  the  widget 

client_data      Specifies  the  pop-up  shell. 

call_data          Specifies  the  callback  data,  which  is  not  used  by  this  procedure. 

Description 

See  xtCallbackExclusive. 
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„    „  J  XtCallbackNonexciusive 

— Xt  -  Pop  Ups 

Name 

XtCallbackNonexciusive  —  callback  function  to  pop  up  a  widget 

Synopsis 

void  XtCallbackNonexciusive (w,  client_data,  call_data) 
Widget  w; 

XtPointer  client_data; 
XtPointer  call_data; 

Arguments 

w  Specifies  the  widget 

clie/5t_data      Specifies  the  pop-up  shell. 

ca  1  l_da  ta          Specifies  the  callback  data,  which  is  not  used  by  this  procedure. 

Description 

See  XtCallbackExclusive. 
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XtCallbackPopdown 

Xt  -  Pop  Ups— 

Name 

XtCallbackPopdown  —  pop  down  a  widget  from  a  callback  routine. 

Synopsis 

void  XtCallbackPopdown (w,  client_data,  call_data) 
Widget  w; 

XtPointer  client_data; 
XtPointer  call_data; 

Arguments 

w  Specifies  the  widget 

client_data      Specifies  a  pointer  to  the  xtPopdownlD  structure. 
call_data          Specifies  the  callback  data,  which  is  not  used  by  this  procedure. 

Description 

XtCallbackPopdown  is  a  built-in  callback  function  for  popping  down  a  pop-up  shell 
widget  This  function  is  suitable  for  popping  down  shells  that  were  previously  popped  up  with 
XtCallbackNone,  XtCallbackNonexclusive,  or  XtCallbackExclusive.  An 
XtPopdownlD  in  the  client_  data  field  indicates  which  widget  is  to  be  popped  down. 

Structures 

XtCallbackPopdown  casts  the  client  data  parameter  to  an  XtPopdownlD  pointer: 

typedef  struct    { 

Widget   shell_widget; 

Widget   enable_widget; 
}    XtPopdownlDRec,    *XtPopdownID; 

shell_widget  is  the  pop-up  shell  to  pop  down,  and  enable_widget  is  the  widget  that 
was  used  to  pop  it  up. 

XtCallbackPopdown  calls  XtPopdown  with  the  specified  shell_widget  and  then  calls 
XtSetSensitive  to  resensitize  the  enable_widget. 

Here  is  an  example: 

Widget  pshell,  confirm; 
XtPopdownlDRec  pop_rec; 

main()  { 

confirm  =  XtCreateWidget (...); 

pshell  =  XtCreatePopupShell (...); 

pop_rec.shell_widget  =  pshell; 

pop_rec.enable_widget  =  confirm; 

XtAddCallback (confirm, XtNcallback, XtCallbackPopdown, pop_rec) ; 


128  X  Toolkit  Intrinsics  Reference  Manual 


Xt-PopUps 


(continued) 


XtCallbackPopdown 


When  the  widget  invokes  xtCallCallbacks  on  its  resource  XtNcallback,  the  pop-up 
shell  pshell  will  be  popped  down.  See  the  companion  example  in  xtCallback- 
Exclusive. 

See  Also 

XtCallbackExclusive(l\  XtCallCallbacks(l),  XtPopdown(l\  XtSetSensitive(\). 
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XtCallbackReleaseCacheRef 

•Xt  -  Resource  Management — 

Name 

XtCallbackReleaseCacheRef  —  callback  function  to  release  a  cached  resource  value. 

Synopsis 

void  XtCallbackReleaseCacheRef (object,  client_data,  call_data) 
Widget  object; 
XtPointer  client_data; 
XtPointer  call_data; 

Arguments 

object  Specifies  the  object  with  which  the  resource  is  associated. 

client_data      Specifies  the  conversion  cache  entry  to  be  released. 
call_data  Is  ignored. 

Description 

This  callback  procedure  may  be  added  to  a  callback  list  to  release  a  previously  returned  xt- 
CacheRef  value.  When  adding  the  callback,  the  callback  client_data  argument  must  be 
specified  as  the  value  of  the  xtCacheRef  data  cast  to  XtPointer. 

See  Also 

XtAppReleoseCacheRefs(\\  XtAppSe(TypeConverter(\\  XtCallbackReleaseCacheRefList(\\  XtCall- 
Converter(l\  XtConvertAndStore(\\  XtSe(TypeConverter(\\ 
XtDestructor  (2),  XffypeConverter  (2). 
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J     XtCallbackReleaseCacheRefList 

— Xt  -  Resource  Management ' 

Name 

XtCallbackReleaseCacheRefList  —  callback  function  to  release  a  list  of  cached  values. 

Synopsis 

void  XtCallbackReleaseCacheRefList (object,  client_data,  call_data) 
Widget  object; 
XtPointer  client_data; 
XtPointer  call_data; 

Arguments 

object  Specifies  the  object  with  which  the  resources  are  associated. 

cl  i  en  t_ da  t  a      Specifies  the  conversion  cache  entries  to  be  released, 
ca  1 1_  da  t  a          Is  ignored. 

Description 

This  callback  procedure  may  be  added  to  a  callback  list  to  release  a  list  of  previously  returned 
XtCacheRef  values.  When  adding  the  callback,  the  callback  client_data  argument  must 
be  specified  as  a  pointer  to  a  NULL-terminated  list  of  XtCacheRef  values. 

See  Also 

XtAppReleoseCocheRefs(\\  XtAppSe(TypeConverter(\\  XtCollbackReleoseCocheRefd),  XtCall- 
Converter(\\  XtConvertAndStore(\),  XtSe(TypeConverter(l\ 
XtDestructor  (2),  XtTypeConverter  (2). 
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N Xt  -  Callbacks  — 

Name 

XtCallCallbackList  —  execute  the  procedures  in  a  callback  list,  specifying  the  callback  list  by 
address. 

Synopsis 

void  XtCallCallbackList (object,  callbacks,  call_data) 
Widget  object; 
XtCallbackList  callbacks; 
XtPointer  call_data; 

Arguments 

object  Specifies  the  object  instance  which  contains  the  callback  list;  may  be  of  class 

Object  or  any  subclass  thereof. 

callbacks         Specifies  the  callback  list  to  be  executed. 

call_data         Specifies  a  callback-list  specific  data  value  to  pass  to  each  of  the  callback 
procedures  in  the  list. 

Description 

The  callbacks  argument  must  specify  the  contents  of  a  widget  or  object  resource  declared 
with  representation  type  XtRCallbacJc.  If  callbacks  is  NULL,  XtCallCallbackList 
returns  immediately. 

See  Also 

XtAddCollbock(\\  XtAddCallbacks(l),  XtCallCallbacks(l),  XtHasCallbacks,  XtRemoveAllCallbacks(\), 
XtRemaveCallback(\\  XtRemoveCallbacks(\\ 
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f  XtCallCallbacks 


Name 

XtCallCallbacks  —  execute  the  procedures  in  a  widget's  callback  list. 

Synopsis 

void  XtCallCallbacks (object,  callback_name,  call_data) 
Widget  object; 
String  callback_name; 
XtPointer  call_data; 

Arguments 

object  Specifies  the  object;  may  be  of  class  Object  or  any  subclass  thereof. 

callback_name  Specifies  the  resource  name  of  the  callback  list  to  be  executed. 
call_data         Specifies  the  value  to  pass  to  each  callback  procedure  as  its  third  argument. 

Description 

XtCallCallbacks  is  used  to  execute  the  callbacks  in  a  given  callback  list.  The  callback  list 
is  specified  by  resource  name. 

The  call_data  argument  is  a  (32-bit)  longword.  The  actual  form  of  the  data  in  the  argument 
must  be  agreed  on  in  advance  by  the  callback  function  and  the  widget  invoking  it  through  xt  - 
CallCallbacks.  The  longword  can  be  used  to  represent  an  address  if  more  data  is  to  be 
passed  to  the  callback  procedure. 

If  no  data  is  needed,  the  call_data  argument  should  be  NULL.  (For  example,  the  xt- 
Ncallback  callback  list  in  the  Athena  Command  widget  needs  only  to  notify  its  clients  that 
the  button  has  been  activated.  No  data  is  passed  in.) 

XtCallCallbacks  ensures  that  if  a  callback  procedure  itself  adds  callbacks  (with  xtAdd- 
Callbacks),  no  unwanted  recursion  ensues. 

Callback  lists  are  maintained  in  an  internal  compiled  form.  Callback  lists  can  be  accessed  out 
side  the  widget  as  resources  but  cannot  be  added,  deleted,  or  invoked  except  through  one  of  the 
Intrinsics  functions  (such  as  XtAddCallback)  provided  to  access  them.  The  Intrinsics  them 
selves  make  sure  that  resources  of  type  Callback  get  compiled  into  this  internal  form. 

For  more  information  on  how  to  explicitly  compile  callbacks  as  resources  of  type  Xt- 
RCallback,  see  XtConvertandStore. 

See  Also 

XtAddCallback(l\  XtAddCallbacks(\\  XtRemoveAllCallbacks(l),  XtRemoveCallbacks(l), 
XtCallbackProc(2). 
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XtCallConverter 

•Xt  -  Resource  Management — 

Name 

XtCallConverter  —  explicitly  invoke  resource  conversions. 

Synopsis 

Boolean  XtCallConverter (display,  converter,  args,  num_args,  from, 

to_in_out,  cache_ref_return) 
Display*  display; 
XtTypeConverter  converter; 
XrmValuePtr  args; 
Cardinal  num_args; 
XrmValuePtr  from; 
XrmValuePtr  to_in_out; 
XtCacheRef  *cache_ref_return; 

Arguments 

display  Specifies  the  display  with  which  the  conversion  is  to  be  associated. 

converter          Specifies  the  new-style  conversion  procedure  to  be  called. 

args  Specifies  the  additional  conversion  arguments  needed  to  perform  the  conver 

sion,  or  specifies  NULL. 

num_args  Specifies  the  count  of  additional  arguments,  or  specifies  zero. 

from  Specifies  a  descriptor  for  the  source  value. 

to_in_out          Returns  the  converted  value. 

cache_ref_return 

Returns  a  conversion  cache  ID. 

r 

Description 

XtCallConverter  looks  up  the  specified  type  converter  in  the  application  context  associ 
ated  with  the  display.  If  the  converter  was  not  registered  or  was  registered  with  cache  type  xt- 
CacheAll  or  XtCacheByDisplay,  XtCallConverter  looks  in  the  conversion  cache  to 
see  whether  this  conversion  procedure  has  been  called  with  the  specified  arguments.  If  so,  Xt 
CallConverter  checks  the  success  status  of  the  prior  call.  If  the  conversion  failed,  Xt 
CallConverter  returns  False  immediately;  otherwise  it  checks  the  size  specified  in  the 
to_in_out  argument. 

If  this  size  is  greater  than  or  equal  to  the  size  stored  in  the  cache,  XtCallConverter: 

•  Copies  the  information  stored  in  the  cache  to  the  location  specified  by  the  to_in_out 
argument 

•  Stores  the  cache  size  in  to_in_put->size. 

•  Returns  True. 

If  the  size  specified  in  the  to_in_out  argument  is  smaller  than  the  size  stored  in  the  cache, 
XtCallConverter  copies  the  cache  size  into  to->size  and  returns  False.  If  the 
converter  was  registered  with  cache  type  xtCacheNone  or  if  no  value  was  found  in  the  con 
version  cache,  XtCallConverter  calls  the  converter  and  if  it  was  not  registered  with  cache 
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type  XtCacheNone  enters  the  result  in  the  cache.  XtCallConverter  then  returns  what 
the  converter  returned. 

cache_ref_return  specifies  storage  allocated  by  the  caller  in  which  an  opaque  value  will 
be  stored.  If  the  type  converter  has  been  registered  with  the  xtCacheRef  Count  modifier 
and  if  the  value  returned  in  cache_ref_return  is  non-NULL  then  the  caller  should  store  the 
cache_ref_return  value  in  order  to  decrement  the  reference  count  when  the  converted 
value  is  no  longer  required.  cache_ref_return  should  be  specified  as  NULL  if  the  caller  is 
unwilling  or  unable  to  store  the  value. 

See  Also 

XtConvertAndStore(\ ),  XtSe(TypeConverter(\), 
XfTypeConverter  (2). 
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XtCalloc  ~\ Y, 

v Xt  -  Memory  Allocation  — 

Name 

XtCalloc  —  allocate  an  array  and  initialize  elements  to  zero. 

Synopsis 

char  *XtCalloc (num,  size); 
unsigned  int  num; 
unsigned  int  size; 

Arguments 

num  Specifies  the  number  of  array  elements  to  allocate. 

si  ze  Specifies  the  size  of  an  array  element  in  bytes. 

Description 

XtCalloc  allocates  space  for  the  specified  number  of  array  elements  of  the  specified  size  and 
initializes  the  space  to  zero.  If  there  is  insufficient  memory  to  allocate  the  new  block,  xt- 
Calloc  terminates  by  calling  XtErrorMsg. 

XtCalloc  differs  from  xtMalloc  in  that  it  stores  zero  in  all  the  array  elements. 

The  function  XtCalloc  is  implemented  by  the  Toolkit  independently  of  the  particular  envi 
ronment,  so  programs  ported  to  a  system  not  supporting  calloc  will  still  work. 

xtNew  and  xtNewString  provide  slightly  higher-level  approaches  to  memory  allocation. 
See  Also 

XtErrorMsg(l\  XtFree(l\  XtMalloc(\\  XtNew(\\  XtNewString(\\  XtRealloc(\\ 
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— Xt  -  Object  Information ' 

Name 

XtCheckSubclass  —  in  DEBUG  mode,  verify  an  object's  class. 

Synopsis 

void  XtCheckSubclass (object,  object_class,  message) 
Widget  object; 
WidgetClass  object_class; 
String  message; 

Arguments 

object  Specifies  the  object;  may  be  of  class  Object  or  any  subclass  thereof. 

object_class         Specifies  the  widget  class  to  test  against;  may  be  of  class  objectClass  or 
any  subclass  thereof. 

message  Specifies  the  message  to  be  used  if  the  widget  is  not  a  subclass  of  the 

specified  object_class. 

Description 

XtCheckSubclass  determines  if  object  object  belongs  to  a  subclass  of  the  specified 
object_class.  (Note  that  two  objects  of  the  same  class  satisfy  this  condition.)  The  object 
can  be  any  number  of  subclasses  removed  and  need  not  be  an  immediate  subclass  of  the  speci 
fied  object  class. 

If  the  object  is  not  a  subclass,  XtCheckSubclass  constructs  an  error  message  from  the 
supplied  message,  the  object's  actual  class,  and  the  expected  class,  and  it  calls  xtErrorMsg. 

XtCheckSubclass  should  be  used  at  the  entry  point  of  exported  routines  to  ensure  that  the 
client  has  passed  in  a  valid  object  class  for  the  exported  operation. 

XtCheckSubclass  is  a  macro.  It  is  only  executed  when  the  object  has  been  compiled  with 
the  compiler  symbol  DEBUG  defined;  otherwise,  it  is  defined  as  the  empty  string  and  generates 
no  code. 

XtCheckSubclass  uses  the  Core  widget  data  structures  to  perform  its  checking. 
See  Also 

XtCloss(\\  XtIsSubcloss(l\  XtSuper  class  (l\ 
Core(3). 
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XtClass  \ Yl 

v Xt  -  Object  Information — 

Name 

XtClass  —  obtain  a  widget's  class. 

Synopsis 

WidgetClass  XtClass (object) 
Widget  object; 

Arguments 

object  Specifies  the  object;  may  be  of  class  Object  or  any  subclass  thereof. 

Description 

XtClass  returns  a  pointer  to  the  widget's  class  structure. 

The  class  is  obtained  by  accessing  the  widget  core  field  core .  widget_class. 

XtClass  is  a  macro  for  programs  that  include  <XlllCoreP.h>.  It  is  a  function  for  application 
programs  that  do  not  have  access  to  the  Core  widget  field  names. 

See  Also 

XtCheckSubclassd),  XtIsSubclass(l\  XtSuper  class  (l\ 
CoreQ). 
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J  XtCloseDisplay 


Name 

XtCloseDisplay  —  close  a  display  and  remove  it  from  an  application  context. 

Synopsis 

void  XtCloseDisplay (display) 
Display  *  display; 

Arguments 

display  Specifies  the  display. 

Description 

XtCloseDisplay  closes  the  specified  display  as  soon  as  it  is  safe  to  do  so.  If  called  from 
within  an  event  dispatch  (for  example,  a  callback  procedure),  XtCloseDisplay  does  not 
close  the  display  until  the  dispatch  is  complete.  Note  that  applications  need  only  call  Xt 
CloseDisplay  if  they  are  to  continue  executing  after  closing  the  display;  otherwise,  they 
should  call  XtDestroyApplicationContext  or  just  exit 

See  Also 

XtApplnitialize(\),XtAppCreateShell(\\XtDestroyApplicotionContext(\). 
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XtConfigu  re  Widget  v 

v Xt  -  Geometry  Management — 

Name 

XtConfigureWidget  —  move  and/or  resize  widget 

Synopsis 

void  XtConfigureWidget  (w,  x,  y,  width,  height,  border_width) 
Widget  w; 
Position  x; 
Position  y; 
Dimension  width; 
Dimension  height; 
Dimension  border_width; 

Arguments 

w  Specifies  the  widget 

x,  y  Specify  the  widget's  new  x  and  y  coordinates. 

width,  height,  border_width 

Specify  the  widget's  new  dimensions. 

Description 

XtConfigureWidget  moves  and/or  resizes  a  widget  according  to  the  specified  width, 
height,  and  position  values.  It  returns  immediately  if  the  specified  geometry  fields  are  the  same 
as  the  old  values.  Otherwise,  XtConfigureWidget  writes  the  new  x,  y,  width,  height, 
and  border_width  values  into  the  widget  and,  if  the  widget  is  realized,  makes  an  Xlib 
XConf  igurewindow  call  on  the  widget's  window. 

If  either  the  new  width  or  the  new  height  is  different  from  its  old  value,  XtConfigure 
Widget  calls  the  widget's  resize  procedure  to  notify  it  of  the  size  change. 

A  parent  widget  can  use  XtConfigureWidget  to  set  the  geometry  of  its  children.  It  may 
also  be  used  to  reconfigure  a  sibling  widget  A  child  widget  can  use  xtMakeGeometry- 
Request  and  xtMakeResizeRequest  to  request  more  space  from  a  parent 

If  only  the  size  of  a  widget  is  to  be  changed,  XtResizeWidget  is  simpler  to  use;  similarly,  if 
oray  the  location  of  a  widget  is  to  be  changed,  use  xtMoveWidget. 

The  x  and  y  coordinates  are  specified  with  respect  to  the  origin  in  the  upper-left  comer  of  the 
screen.  Widget  coordinates  can  be  converted  to  screen  coordinates  with  xtTranslate- 
Cqtords. 

Note  that  once  a  widget  is  resized  or  otherwise  reconfigured  by  its  parent  it  may  need  to  do 
additional  processing  in  its  own  resize  method.  Widgets  usually  need  to  know  when  they  have 
changed  size  so  that  they  can  lay  out  their  displayed  data  again  to  match  the  new  size.  When  a 
parent  resizes  a  child,  it  calls  XtResizeWidget,  which  updates  the  geometry  fields  in  the 
widget  configures  the  window  if  the  widget  is  realized,  and  calls  the  child's  resize  method  to 
notify  the  child.  The  resize  procedure  pointer  is  of  type  XtwidgetProc. 
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If  a  class  need  not  recalculate  anything  when  a  widget  is  resized,  it  can  specify  NULL  for  the 
resize  field  in  its  class  record.  This  is  an  unusual  case  and  should  occur  only  for  widgets  with 
very  trivial  display  semantics.  The  resize  method  takes  a  widget  as  its  only  argument 

See  Also 

XtMakeGeometryRequest(l),  XtMakeResizeRequest(\),  XtMoveWidget(l),  XtResizeWidget(l),  Xt- 
TranslateCoords  ( 1 ). 
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Xt  -  Resource  Management— 

Name 

XtConvert  —  convert  resource  type. 

Synopsis 

void  XtConvert (object,  from_type,  from,  to_type,  to_return) 
Widget  object; 
String  from_type; 
XrmValuePtr  from; 
String  to_type; 
XrmValuePtr  to_return; 

Arguments 

object  Specifies  the  object  to  use  for  additional  arguments  (if  any  are  needed);  may 

be  of  class  Object  or  any  subclass  thereof. 

from_type  Specifies  the  source  type. 

from  Specifies  the  value  to  be  converted. 

to_type  Specifies  the  destination  type. 

t  o_r e t  urn  Returns  the  converted  value. 

Description 

XtConvert  has  been  superseded  by  XtConvertAndStore.  XtConvert  looks  up  the 
appropriate  resource  converter  registered  to  convert  from_type  to  to_type  and  then  calls 
XtDirectConvert  to  convert  from  to  to_return.  If  the  conversion  is  successful, 
to_return .  addr  will  be  non-NULL. 

In  addition,  the  Xmu  library  (miscellaneous  utilities)  contains  converters  between  xtRString 
and  XtRBackingStore,  XtRCursor,  XtRJustify,  XtROrientation,  XtRPixmap, 
and  xtRWidget  and  between  xtRFunction  and  xtRCallback.  See  Chapter  9,  Resource 
Management  and  Type  Conversion,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Man 
ual,  for  details. 

All  resource-fetching  routines  (e.g.,  XtGetSubresources,  XtGetApplication- 
Re sources  as  well  as  the  internal  code  that  reads  the  resource  database  when  a  widget  is 
created)  call  resource  converters  if  the  user-specified  resource  is  represented  in  a  different  form 
from  the  desired  representation.  A  widget  seldom  has  to  access  resource  converters  explicitly 
with  XtConvert  or  XtDirectConvert. 

XtConvert  accesses  the  widget  object  to  obtain  values  for  any  additional  arguments  the 
resource  converter  needs.  The  computation  of  additional  arguments  is  discussed  with  xtApp- 
AddConverter.  XtConvert  invokes  XtDirectConvert  to  perform  the  actual  conver 
sion.  It  is  usually  easier  to  access  resource  conversion  indirectly  through  the  resource  mecha 
nism. 

Structures 

typedef  struct  { 

unsigned  int    size; 
caddr  t         addr; 
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(continued) 


XtConvert 


See  Also 

XtAppAddConverter(l),  XtDirectConvert(\),  XtGetApplicationResources(\),  XtGetSubresources(l). 
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Xt  -  Resource  Management- 


Name 

XtConvertAndStore  —  look  up  and  call  a  resource  converter,  copying  the  resulting  value. 

Synopsis 

Boolean  XtConvertAndStore (object,  from_typet  from,  to_type,  to_in_out) 
Widget  object; 
String  from_type; 
XrmValuePtr  from; 
String  to_type; 
XrmValuePtr  to  in  out; 


Arguments 

object 

from_type 
from 
to_type 
to  in  out 


Specifies  the  object  to  use  for  additional  arguments,  if  any  are  needed,  and 
the  destroy  callback  list;  may  be  of  class  Object  or  any  subclass  thereof. 

Specifies  the  source  type. 
Specifies  the  value  to  be  converted. 
Specifies  the  destination  type. 

Specifies  a  descriptor  for  storage  into  which  the  converted  value  will  be 
returned. 


Description 

XtConvertAndStore  looks  up  the  type  converter  registered  to  convert  from_type  to 
to_type,  computes  any  additional  arguments  needed,  and  then  calls  xtCallConverter 
(or  XtDirect Convert  if  an  old-style  converter  was  registered  with  xt,AddConverter  or 
XtAppAddConverter)  with  the  from  and  to_in_out  arguments.  The  to_in_out 
argument  specifies  the  size  and  location  into  which  the  converted  value  will  be  stored  and  is 
passed  directly  to  the  converter.  If  the  location  is  specified  as  NULL,  it  will  be  replaced  with  a 
pointer  to  private  storage  and  the  size  will  be  returned  in  the  descriptor.  The  caller  is  expected 
to  copy  this  private  storage  immediately  and  must  not  modify  it  in  any  way.  If  a  non-NULL 
location  is  specified,  the  caller  must  allocate  sufficient  storage  to  hold  the  converted  value  and 
must  also  specify  the  size  of  that  storage  in  the  descriptor.  If  the  conversion  succeeds,  Xt 
ConvertAndStore  returns  True;  otherwise  it  returns  False. 

Xt  recognizes  and  converts  between  the  from_ types  and  the  to_ types  shown  in  the  table 
below.  In  addition,  it  is  possible  to  register  custom  converters  using  xtAddConverter. 


from_type 


to_type 


Description 


XtRString 


XtRAcceleratorTable 


XtRBoolean 


XtRBool 


Compiles  a  string  accelerator  table  into  internal  accel 
erator  table  format  (no  need  to  call  XtParse- 
AcceleratorTable). 

Converts  strings   "true,"   "false,"  "yes,"   "no,"   "on," 
"off  to  corresponding  Boolean  value  (case  insensi 
tive). 
Same  as  for  XtRBoolean. 
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(continued) 


XtConvertAndStore 


from  type 


to   type 


Description 


XtRColor 
XtRPixel 
XtRInt 


XtRCursor 

XtRDimension 

XtRDisplay 

XtRFile 

XtRFloat 
XtRFont 


XtRFontStruct 


XtRInt 
XtRPixel 


XtRPosition 

XtRShort 

XtRTranslationTable 


XtRUnsignedChar 

XtRPixel 

XtRColor 

XtRBoolean 

XtRBool 

XtRColor 

XtRDimension 

XtRFloat 

XtRFont 

XtRPixel 

XtRPixmap 

XtRPosition 

XtRShort 

XtRUnsignedChar 


Given  a  standard  X  cursor  name,  returns  a  cursor  ID. 
Converts  a  width  or  height  value  to  aDimension. 
Given  a  display  name,  opens  the  display  and  returns  a 
Display  structure. 

Given  a  filename,  opens  the  file  and  returns  the  file 
descriptor. 

Converts  a  numeric  string  to  floating  point. 
Given  a  font  name,  loads  the  font  (if  it  is  not  already 
loaded)  and  returns  the  font  ID.  See  Appendix  C, 
Specifying  Fonts  and  Colors,  for  more  information  on 
legal  values.  The  value  XtDef  aultFont  will  return 
the  default  font  for  the  screen. 

Given  a  font  name,  loads  the  font  (if  it  is  not  already 
loaded)  and  returns  a  pointer  to  the  Font  Struct 
containing  font  metrics.  The  value  XtDef  aultFont 
will  return  the  default  font  for  the  screen. 
Converts  a  numeric  string  to  an  integer. 
Converts  a  color  name  string  (e.g.,  "red"  or 
"#FFOOOO")  into  the  pixel  value  that  will  produce  the 
closest  color  possible  on  the  hardware.  See  Appendix 
C,  Specifying  Fonts  and  Colors,  for  more  information 
on  legal  values.  The  two  values  XtDefault- 
Background  and  XtDefaultForeground  are 
always  guaranteed  to  exist,  and  to  contrast,  on  any 
server. 

Converts  an  x  or  y  value  to  a  Position. 
Converts  a  numeric  string  to  a  short  integer. 
Compiles  string  translation  table  into  internal  transla 
tion    table    format    (no    need    to    call    Xt  Parse - 
TranslationTable). 
Converts  a  string  to  an  unsigned  char. 
Converts  an  XColor  structure  to  a  pixel  value. 
Converts  a  pixel  value  to  an  XColor  structure. 
Converts  an  int  to  a  Boolean. 
Converts  an  int  to  a  Bool. 
Converts  an  int  to  an  XColor. 
Converts  an  int  to  a  Dimension. 
Converts  an  int  to  a  float. 
Converts  an  int  to  a  Font. 
Converts  an  int  to  a  pixel  value. 
Converts  an  int  to  a  Pixmap. 
Converts  an  int  to  a  Position. 
Converts  an  int  to  a  short. 
Converts  an  int  to  an  unsigned  char. 
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XtConvertAndStore  adds  XtCallbackReleaseCacheRef  to  the  destroy- 
Callback  list  of  the  specified  widget  if  the  conversion  returns  an  xtCacheRef  value.  The 
resulting  resource  should  not  be  referenced  after  the  widget  has  been  destroyed. 

XtCreateWidget  performs  processing  equivalent  to  XtConvertAndStore  when  initial 
izing  the  widget  instance.  Because  there  is  extra  memory  overhead  required  to  implement  ref 
erence  counting,  clients  may  distinguish  those  widgets  which  are  never  destroyed  before  the 
application  exits  from  those  which  may  be  destroyed  and  whose  resources  should  be  deallo 
cated. 

To  specify  whether  or  not  reference  counting  is  to  be  enabled  for  the  resources  of  a  particular 
widget  when  the  widget  is  created,  the  client  can  specify  a  value  for  the  Boolean  resource 
XtNinitialResourcesPer  si  stent,  class  XtCInitialResourcesPer  sis  tent. 

When  XtCreateWidget  is  called,  if  this  resource  is  not  specified  as  False  in  either  the  arg 
list  or  the  resource  database,  then  the  resources  referenced  by  this  widget  are  not  reference 
counted,  regardless  of  how  the  type  converter  may  have  been  registered.  The  effective  default 
value  is  True;  thus  clients  which  expect  to  destroy  one  or  more  widgets  and  want  resources 
deallocated  must  explicitly  specify  False  forXtNinitialResourcesPersistent. 

The  resources  are  still  freed  and  destructors  called  when  xtCloseDisplay  is  called  if  the 
conversion  was  registered  as  XtCacheByDisplay. 

Converters  not  only  are  a  good  labor-saving  device,  but  also  make  it  possible  to  hide  the  details 
of  data  structures  in  the  resource  converter.  For  example,  a  program  can  access  fonts,  files,  and 
application-dependent  data  structures  using  resource  conversions. 

Structures 

r 

typedef  struct  { 

unsigned  int     size; 

caddr_t         addr; 
}  XrmValue,  *XrmValuePtr; 

See  Also 

XtAppSeffypeConverter(\\  XtAppReleaseCacheRefs(\\  XtCallbackReleaseCacheRef(\\  XtCallback- 
ReleaseCacheRefList  ( 1 ), 
XfTypeConverter  (2),  XtDestructor  (2). 
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j  XtConvertCase 

— Xt-  Keyboard  Handling ' 

Name 

XtConvertCase  —  determine  upper-case  and  lower-case  versions  of  a  keysym. 

Synopsis 

void  XtConvertCase (display,  keysym,  lower_return,  upper_return) 
Display  *display; 
KeySym  keysym; 
KeySym  * lower_return; 
KeySym  *upper_return; 

Arguments 

display  Specifies  the  display  that  the  keysym  came  from. 

keysym  Specifies  the  keysym  to  convert. 

lower_return         Returns  the  lower-case  equivalent  of  the  keysym. 
upper_return         Returns  the  upper-case  equivalent  of  the  keysym. 

Description 

XtConvertCase  is  used  to  determine  upper-case  and  lower-case  equivalents  for  a  keysym. 
It  calls  the  case  converter  that  is  currently  registered  to  convert  those  keysyms  and  returns  the 
results.  This  procedure  can  perform  application-specific  shifting  of  characters. 

A  user-supplied  xtKeyProc  may  need  to  use  this  function. 
XtRegisterCaseConverter  can  be  used  to  register  a  new  case  converter. 

For  a  more  detailed  discussion  of  processing  keyboard  input,  see  Chapter  13,  Miscellaneous 
Toolkit  Programming  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 
See  Chapter  9,  The  Keyboard  and  Pointer,  in  Volume  One,  Xlib  Programming  Manual,  for 
more  information  on  keysyms. 

See  Also 

XtRegisterCaseConverter (l\  XtSetKeyTranslator(\),  X(TranslateKey(\),  XfTranslateKeycode(l), 
XtCaseProc(2),  XtKeyProc (2). 
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v Xt  -  Application  Contexts— 

Name 

XtCreateApplicationContext  —  create  an  application  context. 

Synopsis 

XtAppContext  XtCreateApplicationContext () 

Description 

XtCreateApplicationContext  returns  an  application  context,  which  is  an  opaque  type. 
Every  application  must  have  at  least  one  application  context. 

XtAppInitialize  is  a  simplified  interface  to  XtToolkitlnitialize,  XtCreate 
ApplicationContext,  XtDisplaylnitialize,  and  XtAppCreateShell. 

Routines  that  use  an  implicit  context  (like  XtMainLoop  and  xtAddTimeOut)  depend  on  the 
default  context  created  by  Xt  Initialize.  You  cannot  use  these  routines  if  you  initialize  a 
specific  application  context. 

See  Also 

XtAppInitialize  ( 1 ) 
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J  XtCreateApplicationShell 


Name 

XtCreateApplicationShell  —  create  an  additional  top-level  widget 

Synopsis 

Widget  XtCreateApplicationShell (application_name,  widget_class,  args, 

num_args) 

String  application_name;  /*unused*/ 
WidgetClass  widget_class; 
ArgList  args; 
Cardinal  num_args; 

Arguments 

appl icati on_name 

Specifies  the  name  of  the  application  instance. 

widget_ class    Specifies  the  widget  class  that  the  application  top-level  widget  should  be. 
args  Specifies  the  argument  list  in  which  to  set  in  the  WM_COMMAND  property. 

num_args  Specifies  the  number  of  arguments  in  the  argument  list. 

Description 

XtCreateApplicationShell  has  been  superseded  by  XtAppCreateShell.  Xt 
CreateApplicationShell  creates  a  new  logical  application  within  a  program.  This 
function  is  a  simplified  interface  to  XtAppCreateShell.  Since  most  applications  have  only 
one  display,  XtCreateApplicationShell  does  not  require  the  application  to  pass  the 
display  explicitly.  It  also  does  not  allow  the  caller  to  specify  the  resource  class  of  the  applica 
tion.  To  take  advantage  of  the  more  general  functionality,  use  XtAppCreateShell. 

See  Also 

XtAppCreoteShell(\) 
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x«  - 


Name 

XtCreateManagedWidget  —  create  and  manage  a  child  widget. 

Synopsis 

Widget  XtCreateManagedWidget  (name,  widget_classr  parent,  args,  num_args) 
String  name; 

WidgetClass  widget__class; 
Widget  parent; 
ArgList  args; 
Cardinal  num_args; 

Arguments 

name  Specifies  the  text  name  for  the  created  shell  widget. 

widget_class  Specifies  the  widget  class  pointer  for  the  created  widget. 

parent  Specifies  the  parent  widget. 

args  Specifies  the  argument  list  to  override  the  resource  defaults. 

num_args  Specifies  the  number  of  arguments  in  the  argument  list. 

Description 

XtCreateManagedWidget  combines  creation  and  management  of  a  widget  into  one  rou 
tine.  It  calls  XtCreateWidget  and  XtManageChild  consecutively.  XtCreate 
ManagedWidget  or  XtVaCreateManagedWidget  is  the  usual  way  to  create  new  widget 
instances. 

,,f 
See  Also 

XtCreoteWidget(\\  XtManageChild(\\  XtManageChildren(\),  XtVaCreateManagedWidget(\). 
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_x, -  POP  ups / XtCreatePopupShell 

Name 

XtCreatePopupShell  —  create  a  pop-up  shell. 

Synopsis 

Widget  XtCreatePopupShell (name,  widget_class,  parent,  args,  num_args) 
String  name; 

WidgetClass  widget_class; 
Widget  parent; 
ArgList  args; 
Cardinal  num_args; 

Arguments 

name  Specifies  the  text  name  for  the  created  shell  widget. 

widget_class  Specifies  the  widget  class  pointer  for  the  created  shell  widget. 

parent  Specifies  the  parent  widget. 

args  Specifies  the  argument  list  to  override  the  resource  defaults. 

num_args  Specifies  the  number  of  arguments  in  the  argument  list. 

Description 

XtCreatePopupShell  creates  a  pop-up  shell  widget,  suitable  for  containing  one  composite 
or  simple  widget  that  is  to  be  popped  up.  Pop-up  widgets  are  used  to  create  windows  that  are 
descendants  of  the  root  window  (rather  than  the  application's  main  window)  so  that  the  pop-up 
window  can  appear  anywhere  on  the  screen,  not  just  with  the  application.  Therefore,  pop  ups 
have  their  own  shell  widget  parent. 

For  a  widget  to  pop  up,  it  must  be  the  child  of  a  pop-up  widget  shell.  A  pop-up  shell  is  never 
allowed  more  than  one  child,  referred  to  as  the  pop-up  child.  Both  the  shell  and  child  taken 
together  are  referred  to  as  the  pop  up. 

XtCreateManagedWidget  is  used  to  create  the  pop  up's  child  (which  is  the  widget  which 
will  be  visible  to  the  user).  After  the  pop-up  shell  and  its  child  are  created,  the  shell  can  be 
popped  up. 

There  are  currently  two  classes  of  pop-up  shells.  They  are  listed  in  the  table  below  and  defined 
in  <X1  II Shell. h>.  Either  can  be  passed  to  XtCreatePopupShell  as  the  widget_class 
argument 


Shell  Types 


overrideShellWidgetClass 
transient  She  HWidget  Class 


Purpose 


Bypasses  window  management. 
Does  not  bypass  window  management. 


The  overrideShellWidgetClass  window  is  created  with  the  override-redirect  window 
attribute  set,  thereby  forcibly  bypassing  window  management.  transientShellwidget- 
Class  hints  to  the  window  manager  that  it  should  not  decorate  the  window  as  it  would  a  gen 
eral  application  and  asks  it  to  allow  it  to  bypass  its  geometry  management.  The  latter  approach 
is  preferred,  but  the  former  may  be  used  for  dropdown  menus  and  other  short-term  windows. 
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XtCreatePOpUpShell  (continued)  Xt-PopUps 

The  XtCreatePopupShell  function  ensures  that  the  specified  class  is  a  subclass  of  Shell 
and,  rather  than  using  insert_child  to  attach  the  widget  to  the  parent's  children  list,  attaches  the 
shell  to  the  parent's  pop-ups  list  directly.  The  pop-up  shell  is  not  a  normal  child  of  its  par 
ent — a  pop-up  child  is  kept  on  its  parent's  list  of  pop-up  children. 

The  pop-up  shell  accepts  a  resource  callback  list  named  xtNpopupCallback  that  will  get 
called  back  when  the  widget  is  popped  up.  There  is  an  analogous  resource,  xtNpopdown- 
Callback,  that  is  invoked  when  the  widget  is  popped  down.  These  callbacks  provide  the 
opportunity  either  to  make  last-minute  changes  to  a  pop-up  child  before  it  is  popped  up  or  to 
change  it  after  it  is  popped  down.  Note  that  excessive  use  of  pop-up  callbacks  can  make  pop 
ping  up  occur  more  slowly. 

Once  a  pop-up  shell  is  created,  the  single  child  of  the  pop-up  shell  can  be  created  in  one  of 
three  ways: 

•  At  startup,  an  application  can  create  the  child  of  the  pop-up  shell.  This  is  appropriate  for 
pop-ups  that  are  composed  of  a  fixed  set  of  widgets.  The  application  can  change  the  state 
of  the  subparts  of  the  pop-up  child  as  the  application  state  changes.  For  example,  if  an 
application  creates  a  static  menu,  it  can  call  xtSetSensitive  (or,  in  general,  xt- 
SetValues)  on  any  of  the  buttons  that  make  up  the  menu.  Creating  the  pop-up  child  at 
this  time  means  that  pop-up  time  is  minimized,  especially  if  the  application  calls  xt- 
RealizeWidget  on  the  pop-up  shell  at  startup.   When  the  menu  is  needed,  all  the 
widgets  that  make  up  the  menu  already  exist  and  need  only  be  mapped.  The  menu  should 
pop  up  as  quickly  as  the  X  server  can  respond. 

•  An  application  can  postpone  the  creation  of  the  child  until  it  is  needed,  which  minimizes 
application  startup  time,  but  slows  pop-up  time.  This  approach  allows  the  pop-up  child 
to  reconfigure  itself  each  time  it  is  popped  up.  In  this  case,  the  pop-up  child  creation  rou 
tine  should  poll  the  application  to  find  out  if  it  should  change  the  sensitivity  of  any  of  its 
subparts. 

•  An  application  can  use  work  procedures  (XtAddWorkProc)  to  create  the  child  during 
application  idle  time.  This  solves  both  the  above  problems,  but  may  introduce  random 
user  response  delays. 

The  pop-up  shell  accepts  a  resource  function  pointer  (of  type  xtRFunction)  that  gets 
invoked  when  a  widget  is  popped  up.  The  resource  is  named  xtNcreatePopupChild- 
Proc.  It  can  be  used  to  create  the  pop-up  child,  if  one  does  not  exist  at  the  time  the  pop-up  is 
invoked. 

Pop-up  child  creation  does  not  map  the  pop  up,  even  if  you  create  the  child  and  call  xt- 
RealizeWidget  on  the  pop-up  shell.  Pop  ups  can  be  popped  up  through  several  mecha 
nisms: 

•  A  call  to  xt Popup. 

•  One  of  the  supplied  callback  procedures  (for  example,  xtCallbackNone,  xt- 
CallbackNonexclusive,  or  XtCallbackExclusive). 

•  The  standard  translation  action  xtMenuPopup. 
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(continued) 


XtCreatePopupShel! 


For  a  discussion  of  the  underlying  concepts  of  override-redirection,  see  Chapter  4,  An  Example 
Application  in  Volume  One,  Xlib  Programming  Manual. 

See  Also 

XtCallbackExclusive(l),  XtCreateManagedWidget(l),  XtNameToWidget(l),  XtPopdown(l),  XtPopup(l). 
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XtCreateWidget  \ Yi 

v Xt  -  Widget  Lifecycle— 

Name 

XtCreateWidget  —  create  an  instance  of  a  widget 

Synopsis 

Widget  XtCreateWidget (name,  object_class,  parent ,  args,  num_args) 
String  name; 

WidgetClass  object_class; 
Widget  parent; 
ArgList  args; 
Cardinal  num_args; 

Arguments 

name  Specifies  the  resource  name  for  the  created  widget,  or  non- widget  object, 

which  is  used  for  retrieving  resources  and,  for  that  reason,  should  not  be  the 
same  as  any  other  widget  that  is  a  child  of  same  parent 

object_dass    Specifies  the  widget  class  pointer  for  the  created  widget;  may  be  of  class 
objectClass  or  any  subclass  thereof. 

parent  Specifies  the  parent  widget 

args  Specifies  the  argument  list  to  override  the  resource  defaults. 

num_args  Specifies  the  number  of  arguments  in  the  argument  list.  (Note  that  you  can 

determine  the  number  of  arguments  in  a  static  argument  list  using  the  xt- 
Number  macro.) 

Description 

XtCreateWidget  creates  a  new  instance  of  class  object_class.  The  usual  way  to 
access  XtCreateWidget  is  to  combine  creation  and  management  with  xtCreate- 
Managedwidget;  you  will  normally  use  XtCreateWidget  and  XtManageChild  only  in 
cases  where  you  wish  to  create  a  number  of  interrelated  widgets,  and  bring  them  under  parental 
management  at  the  same  time. 

XtCreateWidget  creates  a  new  widget  instance  structure  and  invokes  the  widget's  initiali 
zation  method.  XtCreateWidget  resolves  conflicts  between  values  for  the  arguments  sup 
plied  in  the  environment  with  those  supplied  in  args  in  the  new  widget  instance  structure. 

XtCreateWidget  performs  many  of  the  boilerplate  operations  of  widget  creation: 

•  XtCreateWidget  checks  to  see  whether  the  xtProc  method  has  been  called  for  this 
class  and  for  all  superclasses  and,  if  not,  calls  those  necessary,  in  a  superclass-to-subclass 
order. 

•  XtCreateWidget  issues  a  fatal  error  if  all  of  the  following  conditions  occur: 

—  The  specified  class  is  not  coreWidgetClass  or  a  subclass  thereof. 

—  The  parent  is  a  subclass  of  compositeWidgetClass. 
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—  Either  no  extension  record  in  the  parent's  composite  class  part  extension  field  exists 
with  the  record_type  of  NULLQUARK,  or  the  accepts_ob  jects  field  in  the 
extension  record  is  False. 

•  XtCreateWidget  allocates  memory  for  the  widget  instance. 

•  If  the  parent  is  a  subclass  of  const  raintwidgetClass,  memory  is  allocated  for  the 
parent's  constraints,  and  stores  the  address  of  this  memory  into  the  constraints  field 
of  the  widget 

•  XtCreateWidget  initializes  the  core  nonresource  data  fields  (for  example,  parent 
and  visible). 

•  XtCreateWidget  initializes  the  resource  fields  (for  example,  background_pixel) 
by  using  the  resource  lists  specified  for  this  class  and  all  superclasses. 

•  If  the  parent  is  a  subclass  of  constraintWidgetClass,  XtCreateWidget  initial 
izes  the  resource  fields  of  the  constraint  record  by  using  the  constraint  resource  list  speci 
fied  for  the  parent's  class  and  all  superclasses  up  to  constraintWidgetClass. 

•  XtCreateWidget  calls  the  initialize  procedures  for  the  widget  starting  at  the  Core  ini 
tialize  procedure  and  descending  to  the  widget's  initialize  procedure. 

•  If  the  parent  is  a  subclass  of  compositeWidgetClass,  XtCreateWidget  puts  the 
widget  into  its  parent's  children  list  by  calling  its  parent's  insert_child  method. 

•  If  the  parent  is  a  subclass  of  constraintWidgetClass,  XtCreateWidget  calls 
the  constraint  initialize  methods,  starting  at  constraintWidgetClass  and  descend 
ing  to  the  parent's  constraint  initialize  method. 

Note  that  the  XtCreateWidget  function  gets  resources  as  a  superclass-to-subclass  opera 
tion.  That  is,  the  resources  specified  in  the  Core  resource  list  are  fetched,  then  those  in  the  sub 
class,  and  so  on  down  to  the  resources  specified  for  this  widget's  class.  Within  a  class, 
resources  are  fetched  in  the  order  they  are  declared. 

In  general,  if  a  widget  resource  field  is  declared  in  a  superclass,  that  field  is  included  in  the 
superclass's  resource  list  and  need  not  be  included  in  the  subclass's  resource  list.  For  example, 
the  Core  class  contains  a  resource  entry  for  background_j>ixel.  Consequently,  the  imple 
mentation  of  Label  need  not  also  have  a  resource  entry  for  background_pixel.  However,  a 
subclass,  by  specifying  a  resource  entry  for  that  field  in  its  own  resource  list,  can  override  the 
resource  entry  for  any  field  declared  in  a  superclass.  This  is  most  often  done  to  override  the 
defaults  provided  in  the  superclass  with  new  ones. 

At  class  initialization  time,  resource  lists  for  that  class  are  scanned  from  the  superclass  down  to 
the  class  to  look  for  resources  with  the  same  offset.  A  matching  resource  in  a  subclass  will  be 
reordered  to  override  the  superclass  entry.  (A  copy  of  the  superclass  resource  list  is  made  to 
avoid  affecting  other  subclasses  of  the  superclass.)  Also  at  class  initialization  time,  the  Intrin- 
sics  produce  an  internal  representation  of  the  resource  list  to  optimize  access  time  when  creat 
ing  widgets.  To  save  memory,  the  Intrinsics  may  overwrite  the  storage  allocated  for  the 
resource  list  in  the  class  record;  therefore,  widgets  must  allocate  resource  lists  in  writable  stor 
age  and  must  not  access  the  list  contents  directly  after  the  xtProc  method  has  returned. 
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XtCreateWidget  (continued)  Xt  -  Widget  Lifecycle 

The  Intrinsics-supplied  classes  are  described  in  Object(3),  RectObj(3),  Core(3),  Constraint(3), 
and  Composite(3). 

See  Also 

XtCreateManagedWidget  ( 1 ) 
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— Xt  -  Window  Manipulation ' 

Name 

XtCreate  Window  —  create  widget's  working  window. 

Synopsis 

void  XtCreateWindow  ( wr  window_classr  visual,  value_maskr  attributes) 
Widget  w; 

unsigned  int  window_class; 
Visual  *  visual; 
XtValueMask  value_mask; 
XSetWindowAttributes  ^attributes; 

Arguments 

w  Specifies  the  widget  that  is  used  to  set  the  x,y  coordinates  and  so  on. 

window_class         Specifies   the  Xlib  window  class   (inputOutput,   inputOnly,  or 
CopyFromParent). 

visual  Specifies  the  Xlib  visual  type  (usually  CopyFromParent). 

value_mask  Specifies  which  attribute  fields  to  use. 

attributes  Specifies  the  window  attributes  to  use  in  the  XCreateWindow  call. 

Description 

A  widget  is  responsible  for  creating  its  own  window  when  its  Core  realize  method  is  called. 
Rather  than  call  the  Xlib  XCreateWindow  function  explicitly,  a  realize  method  should 
call  the  Intrinsics  analog  XtCreateWindow,  which  simplifies  the  creation  of  windows  for 
widgets.  XtCreateWindow  calls  the  Xlib  XCreateWindow  function,  merging  values  from 
the  Core  widget  instance  structure  (see  below)  and  attributes.  Then  it  assigns  the  created 
window  to  the  widget's  core  window  field. 

XtCreateWindow  evaluates  the  following  fields  of  the  Core  widget  structure: 

•  depth 

•  screen 

•  parent->core. window 

•  x  and  y 

•  width  and  height 

•  border_width 

The  x,  y,  width,  height,  and  border_width  window  attributes  are  available  to  geometry 
managers.  These  fields  are  maintained  synchronously  inside  the  Intrinsics.  When  an 
XConf  igurewindow  is  issued  on  the  widget's  window  (on  request  of  its  parent),  these  val 
ues  are  updated  immediately  rather  than  sometime  later  when  the  server  generates  a 
ConfigureNotify  event  (In  fact,  most  widgets  do  not  have  SubstructureNotify 
turned  on.)  This  ensures  that  all  geometry  calculations  are  based  on  the  internally  consistent 
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(continued) 


Xt  -  Window  Manipulation 


toolkit  world,  rather  than  on  either  an  inconsistent  world  updated  by  asynchronous 
Conf  igureNotify  events  or  a  consistent  but  slow  world  in  which  geometry  managers  ask 
the  server  for  window  sizes  whenever  they  need  to  lay  out  their  managed  children. 

Window  attributes  are  documented  more  fully  in  Volume  One,  Xlib  Programming  Manual,  and 
Volume  Two,  Xlib  Reference  Manual;  see  XSetwindowAttributes  for  a  summary. 


Structures 

typedef  struct  { 

Pixmap  background_pixmap;  Xv 
unsigned  long  background_pixel; /* 

Pixmap  border_pixmap;  /i 

unsigned  long  border_pixel;  /i 

int  bit_gravity;  /i 

int  win_gravity;  /i 

int  backing_store;  /i 

unsigned  long  backing_planes;  X1 

unsigned  long  backing_pixel;  /' 

Bool  save_under;  /' 

long  event_mask;  X1 

long  do_not_propagate_mask;  /' 

Bool  override_redirect;  X1 

Colormap  colormap;  X1 

Cursor  cursor;  X1 

}  XSetwindowAttributes; 


background  or  None  or  ParentRelative  *  I 
background  pixel  */ 
border  of  the  window  */ 
border  pixel  value  *  I 
one  of  bit  gravity  values  *X 
one  of  the  window  gravity  values  *  I 
NotUseful,  WhenMapped,  Always  *X 
planes  to  be  preserved  if  possible  *X 
value  to  use  in  restoring  planes  *  I 
should  bits  under  be  saved  (popups)  */ 
set  of  events  that  should  be  saved  */ 
set  of  events  that  should  not  propagate  ' 
boolean  value  for  override-redirect  */ 
colormap  to  be  associated  with  window  */ 
cursor  to  be  displayed  (or  None)  */ 


I*  Definitions  for  valuemask  argument.   These  control  which  fields  in 
*  XSetwindowAttributes  structure  should  be  used. 

*/ 

r 
#define  CWBackPixmap  (1L«0) 

#define  CWBackPixel  (1L«1) 

#define  CWBorderPixmap  (1L«2) 

tdefine  CWBorderPixel  (1L«3) 

#define  CWBitGravity  (1L«4) 

#define  CWWinGravity  (1L«5) 

#define  CWBackingStore  (1L«6) 

#define  CWBackingPlanes  (1L«7) 

#define  CWBackingPixel  (1L«8) 

#define  CWOverrideRedirect  (1L«9) 

tdefine  CWSaveUnder  (1L«10) 

#define  CWEventMask  (1L«11) 

tdefine  CWDontPropagate  (1L«12) 

tdefine  CWColormap  (1L«13) 

tdefine  CWCursor  (1L«14) 


See  Also 

realize  (4) 


158 


X  Toolkit  Intrinsics  Reference  Manual 


/  XtDatabase 

— Xt  -  Resource  Management ' 

Name 

XtDatabase  —  obtain  the  resource  database  for  a  particular  display. 

Synopsis 

XrmDatabase  XtDatabase (display) 
Display  * display ; 

Arguments 

display  Specifies  the  display  for  which  the  resource  database  should  be  returned. 

Description 

XtDatabase  returns  the  complete  resource  database  built  by  xtDisplaylnitialize  that 
is  associated  with  display.  The  contents  of  the  database  are  fully  merged  from  resource  val 
ues  on  the  server  and  command  line  arguments. 

If  display  has  not  been  initialized  by  XtDisplaylnitialize,  the  results  are  not 
defined. 

The  type  XrmDatabase  should  be  treated  as  opaque  and  should  not  be  manipulated  directly 
except  with  Xlib  functions  (XrmPutResource,  XrmQPutResource,  XrmGetResource, 
XrmQGetResource,  etc.). 

XtAppInitialize,  XtGetResourceList,  and  XtGetSubresources  provide  a  more 
manageable  approach  to  obtaining  resources. 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 

Command-line  arguments  and  a  complete  example  using  alternate  command  line  parsing  are 
presented  in  Chapter  9,  Resource  Management  and  Type  Conversion,  in  Volume  Four,  X 
Toolkit  Intrinsics  Programming  Manual. 

See  Also 

XtAppInitialize  (I),  XtDisplayInltialize(\\  XtGetResourceList(\\  XtGetSubresources  (I). 
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XtDestroyApplicationContext      \ Y| 

> Xt  -  Application  Contexts— 

Name 

XtDestroyApplicationContext  —  destroy  an  application  context  and  close  its  displays. 

Synopsis 

void  XtDestroyApplicationContext (app_ con  text) 
XtAppContext  app_context; 

Arguments 

app_context      Specifies  the  application  context. 

Description 

XtDestroyApplicationContext  destroys  the  specified  application  context  as  soon  as  it 
is  safe  to  do  so.  If  called  from  within  an  event  handler  or  a  callback  procedure,  XtDestroy 
ApplicationContext  does  not  destroy  the  application  context  until  the  dispatch  is  com 
plete. 

X  Toolkit  applications  need  not  call  XtDestroyApplicationContext  unless  they  use 
multiple  application  contexts  and  want  to  destroy  one.  Most  applications  can  exit  using  the 
standard  method  for  their  operating  system  (typically,  by  calling  exit  for  POSIX-based  sys 
tems).  The  quickest  way  to  make  the  windows  disappear  while  exiting  is  to  call  xtUnmap- 
widget  on  each  top-level  shell  widget.  The  X  Toolkit  has  no  resources  beyond  those  in  the 
program  image,  and  the  X  server  will  free  its  resources  when  its  connection  to  the  application  is 
broken. 

See  Also 

XtCreoteApplicationContext(\)  -' 
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v    „        All    #l    XtDestroyGC 

— Xt  -  Memory  Allocation ' 

Name 

XtDestroyGC  —  Release  2  compatible  function  to  free  read-only  GCs. 

Synopsis 

void  XtDestroyGC (gc) 
GC  gc; 

Arguments 

w  Specifies  the  widget 

gc  Specifies  the  GC  to  be  deallocated. 

Description 

XtDestroyGC  is  superseded  by  XtReleaseGC.  XtDestroyGC  deallocates  a  shared  (read 
only)  Graphics  Context.  References  to  shareable  GCs  are  counted,  and  a  free  request  is  gen 
erated  to  the  server  when  the  last  user  of  a  given  GC  destroys  it.  Note  that  some  earlier  ver 
sions  of  XtDestroyGC  had  only  a  gc  argument  Therefore,  this  function  is  not  very  portable. 
In  addition,  XtDestroyGC  is  only  guaranteed  to  work  properly  if  there  is  exactly  one  open 
display  in  the  application. 

Programs  running  under  Release  3  and  later  should  be  converted  to  use  XtReleaseGC. 
See  Also 

XtGetGC(\\  XtReleaseGC '(1). 
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XtDestroyWidget  _ 

Xt  -  Widget  Lifecycle— 

Name 

XtDestroyWidget  —  destroy  a  widget  instance. 

Synopsis 

void  XtDestroyWidget (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  to  be  destroyed;  may  be  of  class  Object  or  any  subclass 

thereof. 

Description 

Most  applications  simply  exit,  causing  widgets  to  be  destroyed  automatically.  XtDestroy 
Widget  destroys  widgets  explicitly.  It  can  be  used  by  an  application  to  destroy  widgets  that 
are  no  longer  needed.  It  can  also  be  used  by  widgets  that  need  to  destroy  themselves.  It  can  be 
called  at  any  time,  including  from  a  callback  routine  of  the  widget  being  destroyed. 

Widget  destruction  occurs  in  two  phases  to  prevent  dangling  references  to  destroyed  widgets. 
In  phase  one,  XtDestroyWidget  performs  the  following: 

•  If  the  being_dest  royed  field  of  the  widget  is  True,  it  returns  immediately; 

Otherwise,  it  recursively  descends  the  widget  tree  and  sets  the  being_dest royed 
field  to  True  for  the  widget  and  all  children;  and 

•  It  adds  the  widget  to  a  list  of  widgets  (the  destroy  list)  that  should  be  destroyed  when  it  is 
safe  to  do  so. 

For  entries  on  the  destroy  list,  if  w2  occurs  after  wl  on  the  destroy  list,  then  w2  is  not  a  descen 
dant  of  wl.  (A  descendant  can  be  either  a  normal  child  or  a  pop-up  child.) 

Phase  two  occurs  when  all  procedures  that  should  execute  as  a  result  of  the  current  event  have 
been  called  (including  all  procedures  registered  with  the  Event  and  Translation  Managers). 
That  is,  when  the  current  invocation  of  xtDispatchEvent  is  about  to  return  (or  immedi 
ately  if  notinXtDispatchEvent). 

In  phase  two,  XtDestroyWidget  performs  the  following  on  each  entry  in  the  destroy  list: 

•  Calls  the  destroy  callback  procedures  registered  on  the  widget  (and  all  descendants).  The 
calls  happen  in  reverse  order  (children  callbacks  before  parent  callbacks). 

•  If  the  widget's  parent  is  a  subclass  of  compositeWidgetClass  and  if  the  parent  is 
not  being  destroyed,  XtDestroyWidget  calls  XtUnmanageChild  on  the  widget 
and  then  calls  the  widget's  parent's  delete_child  method. 

•  If  the  widget's  parent  is  a  subclass  of  constraintwidgetClass,  it  calls  the  con 
straint  destroy  procedure  for  the  parent,  then  the  parent's  superclass,  until  finally  it  calls 
the  constraint  destroy  procedure  for  constraintwidgetClass. 
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Xt  -  Widget  Lifecycle  (continued)  XtDeStroyWidget 

Calls  the  destroy  methods  for  the  widget  (and  all  descendants)  in  post-order.  For  each 
such  widget,  it  calls  the  destroy  procedure  declared  in  the  widget  class,  then  the  destroy 
procedure  declared  in  its  superclass,  until  finally  it  calls  the  destroy  procedure  declared 
in  the  Core  class  record. 

Calls  the  Xlib  function  XDestroyWindow  if  the  widget  is  realized  (that  is,  has  an  X 
window).  The  server  recursively  destroys  all  descendant  windows. 

•         Recursively  descends  the  tree  and  deallocates  all  pop-up  widgets,  constraint  records, 
callback  lists  and,  if  the  widget  is  a  subclass  of  compositeWidgetClass,  children. 

When  an  application  needs  to  perform  additional  processing  during  the  destruction  of  a  widget, 
it  should  register  a  destroy  callback  procedure  for  the  widget  The  destroy  callback  list  is  iden 
tified  by  the  resource  name  XtNdestroyCallback. 

The  following  example  adds  an  application-supplied  destroy  callback  procedure  called 
ClientDestroy  with  client  data  to  a  widget: 

XtAddCallback(w,  XtNdestroyCallback,  ClientDestroy,  client_data) 

Similarly,  the  following  example  removes  the  application-supplied  destroy  callback  procedure 
ClientDestroy: 

XtRemoveCallback(w,  XtNdestroyCallback,  ClientDestroy,  client_data) 

A  widget's  windows  can  be  removed  from  the  display  while  leaving  the  widget  data  structures 
intact  by  calling  xtUnrealizeWidget. 

See  Also 

XtRemoveAllCcdlbacks(\\  XtRemoveCallback(\\  XtUnrealizeWidget(\\ 

XtCallbackProc(2), 

Core®). 
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XtDirectConvert  V 

v Xt  -  Resource  Management — 

Name 

XtDirectConvert  —  perform  resource  conversion  and  cache  result. 

Synopsis 

void  XtDirectConvert  (converter,  args,  num_args,  from,  to__return) 
XtConverter  converter; 
XrmValuePtr  args; 
Cardinal  num_args; 
XrmValuePtr  from; 
XrmValuePtr  to_return; 

Arguments 

converter          Specifies  the  conversion  procedure  to  be  called. 

args  Specifies  the  argument  list  that  contains  the  additional  arguments  needed  to 

perform  the  conversion  (often  NULL). 

num_args  Specifies  the  number  of  additional  arguments  (often  zero). 

from  Specifies  the  value  to  be  converted. 

to_return          Returns  the  converted  value. 

Description 

XtDirectConvert  has  been  superseded  by  XtCallConverter.  XtDirectConvert 
looks  in  the  converter  cache  to  see  if  the  named  conversion  procedure  has  been  called  with  the 
specified  arguments.  If  so,  it  returns  a  descriptor  for  information  stored  in  the  cache;  otherwise, 
it  calls  converter  and  enters  the  result  in  the  cache. 

Before  calling  the  specified  converter,  XtDirectConvert  sets  the  return  value  size  to  zero 
and  the  return  value  address  to  NULL.  If  the  conversion  succeeds,  to_return .  address  will 
be  non-NULL. 

XtConvert  provides  a  higher-level  interface  to  XtDirectConvert.  Converters  can  also 
be  invoked  using  the  xtVaTypedArg  syntax  in  XtVaCreateManagedWidget  or  xt- 
VaSetValues. 

Structures 

typedef  struct  { 

unsigned  int     size; 

caddr_t         addr; 
}  XrmValue,  *XrmValuePtr; 

See  Also 

XtAppAddConverter(\\  XtCoIlConverter(l),  XtConvert(l),  XtConvertAndStore(\\  XtGetApplicotlon- 
Resources(\\  XtGetSubresources(l),  XtSe(TypeConverter(l\  XtVaCreoteMonagedWidget(\\  XtVaSet- 
Values(\\ 
XtConverter  (2). 
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—  Xt- Selections - 


/  XtDisownSelection 


Name 

XtDisownSelection  —  indicate  that  selection  data  is  no  longer  available. 

Synopsis 

void  XtDisownSelection ( w,  selection,  time) 
Widget  w; 
Atom  selection; 
Time  time; 

Arguments 

w  Specifies  the  widget  relinquishing  selection  ownership. 

selection         Specifies  which  selection  the  widget  is  giving  up  (XA_PRIMARY  or  XA_SEC- 
ONDARY). 

time  Specifies  the  timestamp  that  indicates  when  the  selection  is  relinquished. 

Description 

Usually  the  Intrinsics  selection  mechanism  informs  an  application  when  one  of  its  widgets  has 
lost  ownership  of  the  selection.  However,  in  response  to  some  user  actions  (for  example,  when 
a  user  deletes  the  information  selected),  the  application  should  use  XtDisownSelection  to 
inform  the  Intrinsics  explicitly  that  its  widget  no  longer  should  be  the  selection  owner. 

XtDisownSelection  renounces  ownership  of  a  selection.  It  informs  the  Intrinsics  that  new 
requests  for  selection  data  should  be  directed  elsewhere.  No  subsequent  requests  will  be  sent  to 
the  xtConvertProc  registered  when  the  widget  called  xtOwnSelection. 

If  the  widget  does  not  currently  own  selection,  either  because  it  lost  the  selection  or 
because  it  never  had  the  selection  to  begin  with,  XtDisownSelection  does  nothing. 

After  a  widget  has  called  XtDisownSelection,  its  XtConvertProc  is  not  called  even  if 
a  request  arrives  with  a  timestamp  indicating  the  period  that  it  owned  the  selection.  However, 
its  XtDoneProc  will  be  called  if  a  conversion  that  started  before  the  call  to  XtDisown 
Selection  finishes  after  the  call  to  XtDisownSelection. 

If  the  selection  has  changed  hands  because  another  client  has  claimed  it  (rather  than  as  a  result 
of  a  call  to  XtDisownSelection),  the  Intrinsics  inform  the  application  of  the  loss  by  calling 
its  XtLoseSelectionProc. 

An  example  widget  that  sends  and  receives  data  using  selection  is  presented  in  Chapter 
10,  Interclient  Communications,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 

See  Also 

XtGetSelectionValue  ( 1 ),  XtOwnSelection  ( 1 ), 
XtConvertProc(2),  XtDoneProc (2),  XtLoseSelectionProc(2). 
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XtDispatch  Event  \ Y| 

v Xt  -  Event  Handling  — 

Name 

XtDispatchEvent  —  dispatch  registered  handlers  for  an  event 

Synopsis 

void  XtDispatchEvent (event) 
XEvent  * event; 

Arguments 

event  Specifies  a  pointer  to  the  event  structure  to  be  dispatched  to  the  appropriate 

event  handler. 

Description 

XtDispatchEvent  sends  events  to  handler  functions  previously  registered  with  xtAdd- 
Event Handler.  Since  the  entire  translation  manager  is  an  event  handler,  XtDispatch 
Event  results  in  action  functions  being  called  if  a  translation  matches  the  event  being 
dispatched.  XtDispatchEvent  calls  the  appropriate  handler  functions  and  passes  them  the 
widget,  the  event,  and  client-specific  data. 

If  no  handlers  for  the  event  are  registered,  the  event  is  ignored.  If  there  are  multiple  handlers 
registered  for  an  event,  the  order  in  which  handlers  are  called  is  undefined. 

XtDispatchEvent  returns  True  if  it  dispatched  the  event  to  some  handler  and  False  if  it 
found  no  handler  to  dispatch  the  event  to.  In  most  applications,  xtAppMainLoop  is  used  to 
dispatch  events  transparently.  xtAddEventHandler  and  xtAddRawEventHandler  are 
used  to  register  event  handlers. 

The  most  common  use  of  XtDispatchEvent  is  to  dispatch  events  acquired  with  xtApp- 
NextEvent.  However,  it  also  can  be  used  to  dispatch  user-constructed  events.  Xt 
DispatchEvent  records  the  last  timestamp  in  any  event  which  contains  a  timestamp  (see 
XtLastTimestampProcessed)  and  also  is  responsible  for  implementing  the  grab  seman 
tics  of  XtAddGrab. 

See  Also 

XtAddEventHandler  (I),  XtAddGrab(l),  XtAddRawEventHandler  (I),  XtAppNextEvent(\),  XtEvent- 
Handler(\\  XtMainLoop(l). 
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— Xt-  Object  Information ' 

Name 

XtDisplay  —  return  the  display  pointer  for  the  specified  widget. 

Synopsis 

Display  * XtDisplay (w) 
Widget  w; 

Arguments 

w  Specifies  the  widget  for  which  the  Di  spl  ay  is  to  be  returned. 

Description 

XtDisplay  returns  the  display  pointer  for  the  specified  widget. 

See  Also 

XtScreen(\) 
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XtDisplaylnitialize  \ 

v Xt  -  Application  Contexts— 

Name 

XtDisplaylnitialize  —  initialize  a  display  and  add  it  to  an  application  context. 

Synopsis 

void  XtDisplaylnitialize (app_context,  display,  application_name,  applica- 

tion_classf  options,  num_options,  argc,  argv) 
XtAppContext  app_context; 
Display  *  display; 
String  application_name; 
String  application_class; 
XrmOptionDescRec  *  opt  ions; 
Cardinal  num_options; 
Cardinal  * argc; 
String  *argv; 

Arguments 

app_context      Specifies  the  application  context. 

display  Specifies  the  display.  Note  that  a  display  can  be  in  at  most  one  application 

context. 

appl icati on_name 

Specifies  the  name  of  the  application  instance. 

appl ication_  class 

Specifies  the  class  name  of  this  application.  This  name  is  usually  the  generic 
name  for  all  instances  of  this  application. 

options  Specifies   how  to  parse  the  command  line   for  any  application-specific 

resources.  The  options  argument  is  passed  as  a  parameter  to  XrmParse- 
Command. 

num_options      Specifies  the  number  of  entries  in  the  options  list. 

argc  Specifies  a  pointer  to  the  number  of  command  line  arguments. 

argv  Specifies  the  command  line  arguments. 

Description 

XtDisplaylnitialize  builds  the  resource  database,  parses  the  command  line  using  the 
Xlib  XrmParseCommand  function,  and  performs  other  per-display  initialization.  It  does  not 
actually  open  a  display  connection.  Most  programs  should  use  xtOpenDi splay  instead. 

After  XrmParseCommand  has  been  called,  argc  and  argv  contain  only  those  arguments 
that  were  not  in  the  standard  option  table  or  in  the  table  specified  by  the  options  argument. 
If  the  modified  argc  is  not  zero,  most  applications  simply  print  out  the  modified  argv  along 
with  a  message  listing  the  allowable  options.  On  POSIX-based  systems,  the  application  name  is 
usually  the  final  component  of  argv  [  0  ] .  If  the  synchronize  resource  is  True  for  the  specified 
application,  XtDisplaylnitialize  calls  the  Xlib  XSynchronize  function  to  put  Xlib 
into  synchronous  mode  for  this  display  connection. 
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Xt  -  Application  Contexts 


(continued) 


XtDisplaylnitialize 


If  the  reverseVideo  resource  is  True,  the  Intrinsics  exchange  XtDefaultForeground 
and  XtDef aultBackground  for  widgets  created  on  this  display. 

This  function  is  not  often  used  unless  you  are  creating  multiple  application  contexts,  since  Xt  - 
Applnitialize  provides  a  simplified  interface  to  it  (and  the  other  two  Toolkit  initialize 
functions,  XtCreateApplicationContext  and  XtAppCreateShell). 

See  xtApplnitialize  for  a  complete  description  of  how  the  arguments  are  used. 


Structures 

typedef  enum  { 

XrmoptionNoArg, 
XrmoptionlsArg, 
XrmoptionStickyArg, 
XrmoptionSepArg, 

XrmoptionResArg, 

XrmoptionSkipArg, 
XrmoptionSkipNArgs, 

XrmoptionSkipLine 
}  XrmOptionKind; 


/*  Value  is  ...  */ 

/*  specified  in  OptionDescRec .value  */ 

/*  the  option  string  itself  */ 

/*  characters  immediately  following  option  */ 

/*  next  argument  in  argv  */ 

/*  next  argument  is  input  to  XrmPutLineResource 

/*  Ignore  this  option  and  ...  */ 

/*  the  next  argument  in  argv  */ 

/*  Ignore  this  option  and  ...  */ 

/*  the  next  value  arguments  in  argv  */ 

/*  the  rest  of  argv  */ 


typedef  struct  { 

char  *option;         /*  Option  name  in  argv  */ 

char  *specifier;       /*  Resource  name  (without  application  name) 
XrmOptionKind  argKind;  /*  Which  style  of  option  it  is  */ 
caddr_t  value;         /*  Value  to  provide  if  XrmoptionNoArg  */ 

}  XrmOptionDescRec,  *XrmOptionDescList; 

See  Also 

XtAppCreateShell(\\  XtAppInitialize(l),  XtCreateApplicationContext(\),  XtDatabase(\),  XtOpen- 
Display(\). 


X  Toolkit  Intrinsics  Reference  Manual 


169 


XtDisplayOfObject  \ 

v Xt  -  Object  Information— 

Name 

XtDisplayOfObject  —  return  the  display  pointer  for  the  nearest  ancestor  of  object  that  is  of 
class  Core. 

Synopsis 

Display  *XtDisplayOf Object (object) 
Widget  object; 

Arguments 

object  Specifies  the  object;  may  be  of  class  Object  or  any  subclass  thereof. 

Description 

XtDisplayOfObject  is  identical  in  function  to  xtDisplay  if  the  object  is  a  widget; 
otherwise  XtDisplayOfObject  returns  the  display  pointer  for  the  nearest  ancestor  of  object 
that  is  of  class  Core. 

See  Also 

XtScreenOjObject(l\XtWindowOJObject(l). 
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_xt  -  Resource  Management /      XtDisplayStringConversionWarning 

Name 

XtDisplayStringConversionWarning  —  issue  a  warning  message  during  conversion  of  string 

resource  values. 

Synopsis 

void  XtDisplayStringConversionWarning (display,  from_valuer  to_type) 
Display  * display; 
String  from_valuef  to_type; 

Arguments 

display  Specifies  the  display  connection  with  which  the  conversion  is  associated. 

f  rom_ val  ue       Specifies  the  string  that  could  not  be  converted. 
to_type  Specifies  the  target  representation  type  requested. 

Description 

XtDisplayStringConversionWarning  issues  a  warning  message  using  XtApp- 
WarningMsg  with  name  set  to  conversionError,  type  set  to  string,  class  set  to 
XtToolkitError  and  the  default  message  string  set  to: 

"Cannot   convert   from_value  to  type   to_type" 

To  issue  other  types  of  warning  or  error  messages,  the  type  converter  should  use  xtApp- 
WarningMsg  or  XtAppErrorMsg. 

See  Also 

XtAppWarningMsg  ( 1 ),  XtAppErrorMsg  (I). 
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XtDisplayToApplicationContext    \ 


•Xt -Initialization — 


Name 

XtDisplayToApplicationContext  —  retrieve  the  application  context  associated  with  a  Display. 

Synopsis 

XtAppContext  XtDisplayToApplicationContext (  display  ) 
Display  *  display ; 

Arguments 

display  Specifies  an  open  and  initialized  Display  connection. 

Description 

The  XtDisplayToApplicationContext  function  returns  the  application  context  in 
which  the  specified  display  was  initialized.  If  the  display  is  not  known  to  the  Intrinsics,  an 
error  message  is  issued. 

See  Also 

XtCreoteApplicotionContext ( 1 ),  XtDisplaylnitialize ( 1 ). 
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-Xt  -  Error  Handling /  XtError 

Name 

XtError  —  call  the  low-level  fatal  error  handler. 

Synopsis 

void  XtError (message) 
String  message; 

Arguments 

message  Specifies  the  message  to  be  reported. 

Description 

XtError  is  superseded  by  xtAppError.  Xt  provides  two  levels  of  error  handling: 

A  high-level  interface  that  takes  an  error  name  and  class  and  looks  the  error  up  in  an 
error  resource  database. 

•         A  low-level  interface  that  takes  a  simple  string,  which  is  printed  out  as  the  error  message. 

Application-context-specific  error  handling  is  not  implemented  on  many  systems.  Most  imple 
mentations  will  have  just  one  set  of  error  handlers.  If  different  handlers  are  set  for  different 
application  contexts,  the  one  set  last  may  be  used. 

In  theory,  most  programs  should  use  XtAppErrorMsg,  not  XtAppError,  so  that  the  pro 
grams  can  be  easily  customized  to  provide  international  or  other  custom  error  messages.  How 
ever,  the  low-level  handlers  are  much  easier  to  use. 

XtAppError  calls  the  low-level  fatal  error  handler.  Fatal  errors  are  assumed  to  be  catastro 
phic  and  irrecoverable.  A  warning  error  handler  also  exists  for  errors  that  require  attention  but 
do  not  preempt  a  program  running  correctly  to  a  normal  successful  completion.  (xtApp- 
Warning  calls  the  corresponding  nonfatal  error  handler.  XtAppErrorMsg  and  xtApp- 
WarningMsg  call  the  corresponding  high-level  handlers.) 

See  Also 

XtErrorMsg(\\  XtSetErrorHandler(\),  XtSetWarningMsg(l\  XtWarning(l),  XtWarningMsg(\). 
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XtErrorMsg  \ Yi 

v Xt-  Error  Handling  — 

Name 

XtErrorMsg  —  call  the  high-level  fatal  error  handler. 

Synopsis 

void  XtErrorMsg (name,  type,  class,  default,  params,  num_params) 
String  name; 
String  type; 
String  class; 
String  default; 
String  *params; 
Cardinal  *num_params; 

Arguments 

name  Specifies  the  general  kind  of  error;  for  example,  invalidParameter. 

type  Specifies  the  detailed  name  of  the  error.  This  is  specified  using  print  f -like 

syntax,  with  the  parameters  and  number  of  parameters  specified  by  params 
and  num_params. 

class  Specifies  the  resource  class. 

defa  ul  t  Specifies  the  default  message  to  use  if  no  message  is  found  in  the  database. 

params  Specifies  a  pointer  to  a  list  of  values  to  be  stored  in  the  type  argument  when 

the  message  is  generated. 

num_params       Specifies  the  number  of  values  in  the  parameter  list. 

i 
Description 

XtErrorMsg  is  superseded  by  xtAppErrorMsg.  Xt  provides  two  levels  of  error  handling: 

•  A  high-level  interface  that  takes  an  error  name  and  class  and  looks  the  error  up  in  an 
error  resource  database. 

•  A  low-level  interface  that  takes  a  simple  string,  which  is  printed  out  as  the  error  message. 

The  high-level  functions  construct  a  string  to  pass  to  the  lower-level  interface.  The  name  and 
type  arguments  are  concatenated  to  form  the  "name"  that  is  used  to  look  up  a  message  in  the 
error  database.  On  POSK-based  systems,  the  error  database  is  usually  called 
lusrlliblXHIXtErrorDB. 

In  theory,  most  programs  should  use  XtAppErrorMsg,  not  xtAppError,  so  that  the  pro 
grams  can  be  easily  customized  to  provide  international  or  other  custom  error  messages.  How 
ever,  the  low-level  handlers  are  much  easier  to  use. 

XtAppError  calls  the  low-level  fatal  error  handler.  Fatal  errors  are  assumed  to  be  catastro 
phic  and  irrecoverable.  A  warning  error  handler  also  exists  for  errors  that  require  attention  but 
do  not  preempt  a  program  running  correctly  to  a  normal  successful  completion.  (xtApp- 
Warning  calls  the  corresponding  nonfatal  error  handler.  XtAppErrorMsg  and  xtApp- 
WarningMsg  call  the  corresponding  high-level  handlers.)  The  Intrinsics  internal  errors  all 
have  class  XtToolkitError. 
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Xt- Error  Handling 


(continued) 


XtErrorMsg 


See  Also 

XtError(l),  XtSetErrorHandler(\),  XtSetWarningHandler(l),  XtWarningd),  XtWarningMsgd). 
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XtFindFile  \ Y1 

> Xt- File  Searching  — 

Name 

XtFindFile  —  search  for  a  file  using  substitutions  in  a  path. 

Synopsis 

String  XtFindFile (path,  substitutions,  num_substi tut  ions,  predicate) 
String  path; 

Substitution  substitutions; 
Cardinal  num_substi tut  ions; 
XtFilePredicate  predicate; 

Arguments 

pa  th  Specifies  a  path  of  file  names  including  substitution  characters. 

substitutions  Specifies  a  list  of  substitutions  to  make  into  the  path. 

num_substi tut  ions 

Specifies  the  number  of  substitutions  passed  in. 

predicate         Specifies  a  procedure  called  to  judge  each  potential  file  name,  or  NULL. 

Description 

The  Intrinsics  provide  two  routines  to  look  for  a  file  by  name  using  string  substitutions  in  a  list 
of  file  specifications.  XtFindFile  uses  an  arbitrary  set  of  client-specified  substitutions 
whereas  xtResolvePathname  uses  a  set  of  standard  substitutions  corresponding  to  the 
X/Open  Portability  Guide  language  localization  conventions.  Most  applications  should  use 
XtResolvePathname,  which  calls  XtFindFile. 

XtFindFile  searches  for  a  file.  The  path  argument  specifies  a  string  that  consists  of  a 
series  of  potential  file  names  delimited  by  colons.  Within  each  name,  the  percent  character 
specifies  a  string  substitution  controlled  by  the  following  character.  For  example: 

•  The  character  sequence  %:  (percent  colon)  specifies  an  embedded  colon  that  is  not  a  del 
imiter;  the  sequence  is  replaced  by  a  single  colon. 

•  The  character  sequence  %%  (percent  percent)  specifies  a  percent  character  that  does  not 
introduce  a  substitution;  the  sequence  is  replaced  by  a  single  percent  character. 

•  If  a  percent  character  is  followed  by  any  other  character,  XtFindFile  looks  through  the 
specified  substitutions  for  that  character  in  the  match  field,  and  if  that  character  is  found 
XtFindFile  replaces  the  percent  and  match  characters  with  the  string  in  the  correspond 
ing  substitution  field. 

A  substitution  string  entry  of  NULL  is  equivalent  to  a  pointer  to  an  empty  string.  If  the  operat 
ing  system  does  not  interpret  multiple  embedded  name  separators  in  the  path  (i.e.,  "/"  in 
POSK)  the  same  way  as  a  single  separator,  XtFindFile  will  collapse  multiple  separators  into 
a  single  one  after  performing  all  string  substitutions.  Except  for  collapsing  embedded  separa 
tors,  the  contents  of  the  string  substitutions  are  not  interpreted  by  XtFindFile  and  may 
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therefore  contain  any  operating-system-dependent  characters,  including  additional  name  sepa 
rators.  Each  resulting  string  is  passed  to  the  predicate  procedure  until  a  string  is  found  for 
which  the  procedure  returns  True;  this  string  is  the  return  value  for  xtFindFile.  If  no 
string  returns  a  True  from  the  predicate,  XtFindFile  returns  NULL. 

If  predicate  is  NULL,  an  internal  procedure  is  used.  This  procedure  checks  that  the  file 
exists,  that  it  is  readable,  and  that  it  is  not  a  directory. 

The  caller  must  free  the  returned  string  using  xtFree  when  the  string  is  no  longer  needed. 

Structures 

A  string  substitution  is  defined  by  a  list  of  Substitution  entries. 

typedef   struct    { 

char   match; 

String  substitution; 
}  SubstitutionRec,  *Substitution; 

See  Also 

XtFindFile ( 1 ),  XtResolvePathnome(\\ 
XtFilePredicate(2). 
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XtFree  "\ 

x Xt  -  Memory  Allocation  — 

Name 

XtFree  —  free  an  allocated  block  of  storage. 

Synopsis 

void  XtFree (ptr) ; 
char  *ptr; 

Arguments 

ptr  Specifies  a  pointer  to  the  block  of  storage  to  be  freed. 

Description 

XtFree  returns  storage  previously  allocated  by  xtCalloc  and  xtMalloc  and  allows  it  to 
be  reused.  If  ptr  is  NULL,  XtFree  returns  immediately. 

Calling  the  Toolkit's  XtMalloc  and  XtFree  is  more  portable  and  provides  better  error 
checking  than  calling  system-specific  malloc  and  free.  Deallocating  blocks  of  memory  not 
allocated  by  XtMalloc  would  be  disastrous. 

xtNew  and  XtNewString  provide  slightly  higher-level  approaches  to  memory  allocation. 
See  Also 

XtCalloc(\\  XtErrorMsg(l),  XtMalloc(\\  XtNew(l),  XtNewString  (I),  XtRealloc(l). 
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XtGetActionKeysym 

— Xt  -  Translations  and  Actions ' 

Name 

XtGetActionKeysym  —  retrieve  the  keysym  and  modifiers  that  matched  the  final  event  specifi 
cation  in  the  translation  table  entry. 

Synopsis 

KeySym  XtGetActionKeysym (event,  modifiers_return) 
XEvent*  event; 
Modifiers*  modifiers_return; 

Arguments 

event  Specifies  the  event  pointer  passed  to  the  action  procedure  by  the  Intrin- 

sics. 

modi  fiers_ret urn  Returns  the  modifiers  that  caused  the  match,  if  non-NULL. 
Description 

XtGetActionKeysym  returns  the  keysym  that  matched  the  final  event  specification  in  the 
translation  table,  provided  that: 

•  XtGetActionKeysym  is  called  after  an  action  procedure  has  been  invoked  by  the  Intrin- 
sics  and  before  that  action  procedure  returns, 

•  The  event  pointer  has  the  same  value  as  the  event  pointer  passed  to  that  action  routine,  and 

•  The  event  isaKeyPress  oraKeyRelease. 

XtGetActionKeysym  also  returns  the  modifiers  actually  used  to  generate  this  keysym  if 
modi  fiers_ret  urn  is  non-NULL. 

If  modi  fiers_ret urn  is  NULL,  XtGetActionKeysym  returns  values  according  to  two 
cases: 

•  If  the  event  is  a  KeyPress  or  KeyRelease,  then  XtGetActionKeysym  calls  xt- 
TranslateKeycode  and  returns  the  results. 

•  If  the  event  is  not  a  KeyPress  or  KeyRelease,  then  XtGetActionKeysym  returns 
NoSymbol  and  does  not  examine  modi  fiers_re turn. 

Note  that  if  an  action  procedure  which  was  invoked  by  the  Intrinsics  invokes  a  subsequent 
action  procedure  (and  so  on)  via  XtCallActionProc,  the  nested  action  procedure  may  also 
call  XtGetActionKeysym  to  retrieve  the  Intrinsics'  keysym  and  modifiers. 

See  Also 

XtAppAddActions(\\  XtCallActionProc(l). 
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XtGetAppiicationNameAndClass  \ 

v Xt  -  Application  Contexts— 

Name 

XtGetAppiicationNameAndClass  —  return  the  application  name  and  class  as  passed  to  xt  - 

Displaylnitialize  for  a  particular  Display. 

Synopsis 

void  XtGetAppiicationNameAndClass (display,  name_return,  class_return) 
Display  ^display; 
String   *name_return; 
String   *class_return; 

Arguments 

display  Specifies  an  open  display  connection  that  has  been  initialized  with  xt- 

Di splay Initialize. 

name_return      Returns  the  application  name. 
class_return    Returns  the  application  class. 

Description 

XtGetAppiicationNameAndClass  returns  the  application  name  and  class  passed  to  xt- 
Displaylnitialize  for  the  specified  display.  If  the  display  was  never  initialized  or  has 
been  closed,  the  result  is  undefined.  The  returned  strings  are  owned  by  the  Intrinsics  and  must 
not  be  modified  or  freed  by  the  caller. 

See  Also 

XtDisplaylnitialize  ( 1 ) 
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-X«-  Resource  Management /  XtGetAPPlicatiOnReSOUrCeS 

Name 

XtGetApplicationResources  —  set  application  variables  from  resource  database. 

Synopsis 

void  XtGetApplicationResources  (object,  base,  resources,  nun?_resources, 

argsr  num_args) 
Widget  object; 
XtPointer  base; 
XtResourceList  resources; 
Cardinal  nu/n_resources; 
ArgList  args; 
Cardinal  num_args; 

Arguments 

object  Specifies  the  object  that  identifies  the  resource  database  to  search  (the  data 

base  is  that  associated  with  the  display  for  this  object);  may  be  of  class 
Object  or  any  subclass. 

base  Specifies  the  base  address  of  the  subpart  data  structure  into  which  the 

resources  will  be  written. 

resources          Specifies  the  resource  list  for  the  subpart. 

/jum_resources  Specifies  the  number  of  resources  in  the  resource  list. 

args  Specifies  the  argument  list  to  override  any  other  resource  specifications. 

num_args  Specifies  the  number  of  arguments  in  the  argument  list. 

Description 

XtGetApplicationResources  can  be  used  to  retrieve  resource  settings  that  apply  to  an 
overall  application,  rather  than  to  a  particular  widget.  (Widget  resources  are  automatically 
retrieved  by  XtCreateWidget.) 

First,  XtGetApplicationResources  uses  the  passed  object,  which  is  usually  an  applica 
tion  shell  widget,  to  construct  a  resource  name  and  class  list.  The  full  name  and  class  of  the 
specified  object  (that  is,  including  its  ancestors,  if  any)  is  logically  prepended  to  each  resource 
name  and  class.  Then,  it  retrieves  resources  from  the  argument  list,  the  resource  database,  or 
the  resource  list  default  values.  After  adding  base  to  each  address,  XtGetApplication 
Resources  copies  the  resource  values  into  the  corresponding  base-offset  address.  If  args  is 
NULL,  num_args  must  be  zero.  However,  if  num_args  is  zero,  the  argument  list  is  not  refer 
enced. 

The  portable  and  recommended  way  to  specify  application  resources  is  to  declare  th^m  as 
structure  members  and  pass  a  pointer  to  such  a  structure  as  base;  then  xtOf  f  set  or  xt- 
Of  f  setof  can  be  used  to  specify  resource_of  fset.  (xtOf  f  set  and  xtOf  f  setof 
determine  the  relative  address  of  a  field.)  This  is  how  widget  instance  variables  are  accessed  by 
the  Resource  Manager  in  widget  instances. 

Here  is  a  short  program  that  sets  up  an  application  resource  list  and  accesses  it. 
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XtGetApplicationReSOUrceS 


(continued) 


Xt  -  Resource  Management 


XtGetApplicationResources  may  overwrite  the  specified  resource  list  with  an  equiva 
lent  representation  in  an  internal  format  that  optimizes  access  time  if  the  list  is  used  repeatedly. 
The  resource  list  must  be  allocated  in  writable  storage  and  the  caller  must  not  modify  the  list 
contents  after  the  call  if  the  same  list  is  to  be  used  again.  Any  per-display  resources  fetched  by 
XtGetApplicationResources  will  not  be  freed  from  the  resource  cache  until  the  display 
is  closed. 

/*  res.c  -  access  application  resources  */ 

tinclude  <stdio.h> 

#include  <Xll/StringDef  s  .  h> 
tinclude  <Xll/Intrinsic  .h> 
/* 

*  fields  to  be  filled  in  from  resources 
*/ 

typedef  struct  _instance_variables  { 
String  label; 
XFontStruct  *font_struct; 
long  foreground; 
}  instance_variable_rec; 

static  XtResource  resources  [  ]  =  { 
{ 

XtNforeground, 
XtCForeground, 
XtRPixel,  sizeof  (Pixel)  , 

XtOf  fsetOf  (instance_variable_rec,  foreground)  , 
XtRString,  "XtDefault  Foreground" 


XtNfont, 

XtCFont, 

XtRFontStruct,  sizeof  (XFontStruct 
XtOf  fsetOf  (instance_variable_rec, 
XtRString,  "XtDefaultFont" 


*)  , 

font 


struct) 


XtNlabel, 

XtCLabel, 

XtRString,  sizeof  (String)  , 

XtOf  fsetOf  (instance_variable_rec,  label)  , 

XtRString,  "Default  Label" 


main(argc,  argv) 
int  argc; 
char  **argv; 
{ 

XtAppContext  app_context; 

Widget  toplevel; 
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(continued) 


XtGetApplicationResources 


instance_variable_rec  iv; 

toplevel  =  XtAppInitialize (&app_context,  argv[0],  "my-widget", 
NULL,  0,  &argc,  argv); 

XtGetApplicationResources (toplevel,      /*  widget  */ 

&iv,  /*  base  address  */ 

resources,     /*  resource  */ 
XtNumber (resources)  ,/*  how  many  */ 
NULL,  0);      /*  ArgList  to  merge  */ 

print f("label=%s\n",  iv. label) ; 

All  resource-fetching  routines  (for  example,  xtGetSubresources  and  XtGet 
ApplicationResources)  call  resource  converters  if  the  user  specifies  a  resource  that  is  a 
different  representation  from  the  desired  representation  or  if  the  widget's  default  resource  value 
representation  is  different  from  the  desired  representation. 

Structures 

XtResource  is  defined  as  follows  in  <X  11 /Intrinsic. h>: 


typedef  struct   XtResource  { 


String 

String 

String 

Cardinal 

Cardinal 

String 


resource_name; 
r e sour ce_c lass, • 
resource_type; 
resource_size; 
resource_of f set; /* 
default_type;    /* 
XtPointer  default_addr;    /* 
}  XtResource,  *XtResourceList; 


Resource  name  */ 

Resource  class  */ 

Representation  type  desired  */ 

Size  in  bytes  of  representation  */ 

Offset  from  base  to  put  resource  value  */ 

Representation  type  of  specified  default  */ 

Address  of  resource  default  value  */ 


See  Also 

XtGetSubresources(\\  XtOffset(\\  XtOffsetOf(\). 
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XtGetConstraintResourceList 

•Xt  -  Resource  Management — 

Name 

XtGetConstraintResourceList  —  get  the  constraint  resource  list  structure  for  a  particular 

widget  class. 

Synopsis 

void  XtGetConstraintResourceList (object_classr  resources  return, 

num_resources_return ) 
WidgetClass  object_class; 
XtResourceList  * res ources_re turn; 
Cardinal  *num_resources_return; 

Arguments 

object_ciass  Specifies  the  object  class  to  be  queried;  may  be  of  class  objectClass 

or  any  subclass  thereof. 

resources_return         Returns  the  constraint  resource  list. 

num_resources_return 

Returns  the  number  of  entries  in  the  constraint  resource  list. 

Description 

If  XtGetConstraintResourceList  is  called  before  the  widget  class  is  initialized,  the 
resource  list  as  specified  in  the  widget  class  record  will  be  returned.  If  XtGetConstraint 
ResourceList  is  called  after  the  widget  class  has  been  initialized,  the  merged  resource  list 
for  the  class  and  all  constraint  superclasses  is  returned.  If  the  specified  object_class  is  not 
a  subclass  of  constraintWidgetClass,  *resources_return  is-  set  to  NULL  and 
*num_resources_return  is  set  to  0.  The  list  returned  by  XtGetConstraint 
ResourceList  should  be  freed  using  xtFree  when  it  is  no  longer  needed. 

See  Also 

XtGetResourceList(\) 
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-x,-  Error  Hand.ing  -  /  XtGetErrorDatabase 

Name 

XtGetErrorDatabase  —  obtain  the  error  database. 

Synopsis 

XrmDatabase  *XtGetErrorDatabase  () 

Description 

XtGetErrorDatabase  has  been  superseded  by  XtAppGetErrorDatabase.  Xt's  high- 
level  error  and  warning  message  handlers  use  a  resource-like  database  for  storing  error  mes 
sages.  On  POSIX-based  systems,  the  database  is  usually  stored  in  the  file 
lusrlliblXHIXtErrorDb.  The  XtGetErrorDatabase  function  returns  the  address  of  the 
error  database.  The  Intrinsics  do  a  lazy  binding  of  the  error  database  and  do  not  read  in  the 
database  file  until  the  first  call  to  XtGetErrorDatabaseText. 

For  a  complete  listing  of  all  errors  and  warnings  that  can  be  generated  by  the  Intrinsics,  see 
Appendix  D. 

Structures 

The  type  XrmDatabase  is  opaque  and  should  not  be  manipulated  directly.  The  return  value 
can  be  manipulated  with  the  Xlib  functions  XrmPutResource,  XrmQPutResource,  Xrm- 
GetResource,  XrmQGetResource. 

See  Also 

XtAppGetErrorDatabase(l),  XtAppGetErrorDatabaseText(l),  XtDatabase(\\  XtGetErrorDatabase- 


XtErrorMsgHandler  (2). 
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XtGetErrorDatabaseText  v 

Xt  -  Error  Handling— 

Name 

XtGetErrorDatabaseText  —  obtain  the  error  database  text  for  an  error  or  a  warning. 

Synopsis 

void  XtGetErrorDatabaseText (name,    type,    class,    default,    buffer_return, 

nbytes) 

char  *name,  *type,  *  class; 
char  * default; 
char  *buffer_return; 
int  nbytes; 

Arguments 

name,  type          Specify  the  name  and  type  that  are  concatenated  to  form  the  resource  name  of 
the  error  message. 

class  Specifies  the  resource  class  of  the  error  message. 

def  a  ul  t  Specifies  the  default  message  to  use  if  an  error  database  entry  is  not  found. 

buffer_return  Specifies  the  buffer  into  which  the  error  message  is  to  be  returned. 
nbytes  Specifies  the  size  of  the  buffer  in  bytes. 

Description 

XtGetErrorDatabaseText  has  been  superseded  by  XtAppGetErrorDatabaseText. 
XtGetErrorDatabaseText  returns  the  appropriate  message  from  the  error  database  for 
name  and  type.  If  no  such  entry  exists,  it  returns  the  specified  default  message.  On 
POSIX-based  systems,  the  error  database  is  usually  stored  in  /usr/lib/Xll/XtErrorDb.  Custom 
error  or  warning  messages  should  be  appended  to  this  file.  The  address  of  the  loaded  database 
can  be  returned  by  a  call  to  xtGetErrorDatabase. 

See  Also 

XtAppGetErrorDatobose(l ),  XtAppGetErrorDatabaseText(\\ 
XtErrorMsgHandler  (2). 
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— Xt  -  Graphics  Context- 


XtGetGC 


Name 

XtGetGC  —  obtain  a  read-only,  shareable  GC. 

Synopsis 

GC  XtGetGC (object,  value_maskr  values) 
Widget  object; 
XtGCMask  value_mask; 
XGCValues  *  values; 


Arguments 

object 

value_mask 
values 


Specifies  the  object  with  which  the  GC  is  to  be  associated;  may  be  of  class 
Object  or  any  subclass  thereof. 

Specifies  which  fields  of  the  GC  are  to  be  filled  in  with  widget  data. 
Returns  the  actual  values  for  this  GC. 


Description 

The  Intrinsics  provide  a  mechanism  whereby  widgets  can  share  a  graphics  context  (GC),  reduc 
ing  the  number  of  GCs  created  and  thereby  improving  server  performance.  The  mechanism  is  a 
simple  caching  scheme,  and  all  GCs  obtained  by  means  of  this  mechanism  must  be  treated  as 
read-only.  If  a  changeable  GC  is  needed,  the  Xlib  XGreateGC  function  should  be  used 
instead. 

The  XtGetGC  function  returns  a  sharable,  read-only  GC.  The  parameters  to  this  function  are 
the  same  as  those  for  XGreateGC  except  that  a  widget  is  passed  instead  of  a  display. 

XtGetGC  shares  only  GCs  in  which  all  values  in  the  GC  are  the  same.  In  particular,  it  does  not 
use  the  value_mask  provided  to  determine  which  fields  of  the  GC  a  widget  considers  rele 
vant.  value_mask  is  used  only  to  tell  the  server  which  fields  should  be  filled  in  with  widget 
data  and  which  it  should  fill  in  with  default  values. 

For  a  more  rigorous  account  of  GCs,  see  Volume  One,  Xlib  Programming  Manual. 


Structures 

typedef  unsigned  long 


XtGCMask;  /*  Mask  of  values  that  are  used  by  widget*/ 


typedef  struct  { 
int  function; 
unsigned  long  plane_mask; 
unsigned  long  foreground; 
unsigned  long  background; 
int  line_width; 
int  line_style; 

int  cap_style; 

int  join_style; 
int  fill_style; 

int  fill  rule; 


logical  operation  */ 

plane  mask  */ 

foreground  pixel  */ 

background  pixel  */ 

line  width  */ 

LineSolid,  LineOnOf fDash, 

LineDoubleDash  */ 

CapNotLast,  CapButt, 

CapRound,  CapPro jecting  */ 

JoinMiter,  JoinRound,  JoinBevel  */ 

FillSolid,  FillTiled, 

FillStippled,  FillOpaqueStippled  */ 

EvenOddRule,  WindingRule  */ 
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XtGetGC 


(continued) 


Xt  -  Graphics  Context 


int  arc_mode; 
Pixmap  tile; 
Pixmap  stipple; 
int  ts_x_origin; 
int  ts_y_origin; 
Font  font; 
int  subwindow_mode; 
Bool  graphics_exposures; 
int  clip_x_origin; 
int  clip_y_origin; 
Pixmap  clip_mask; 
int  dash_offset; 
char  dashes; 
}  XGCValues; 


/*  ArcChord,  ArcPieSlice  */ 

/*  tile  pixmap  for  tiling  operations  */ 

/*  stipple  1  plane  pixmap  for  stipping  */ 

/*  offset  for  tile  or 

*  stipple  operations  */ 

/*  default  text  font  for  text  operations  */ 

/*  ClipByChildren,  Includelnferiors  */ 

/*  should  exposures  be  generated?  */ 

/*  origin  for  clipping  */ 

/*  bitmap  clipping;  other  calls  for  rects  */ 

/*  patterned/dashed  line  information  */ 


See  Also 

XtReleaseGCd) 
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J  XtGetKeysymTable 

— Xt-  Keyboard  Handling ' 

Name 

XtGetKeysymTable  —  return  a  pointer  to  the  keysym-to-keycode  mapping  table  for  a  particu 
lar  display. 

Synopsis 

KeySym  ^XtGetKeysymTable (display,  min_keycode_return,  keysyms_per_key- 

code_return) 
Display  *  display; 
KeyCode  *min_keycode_return; 
int  *keysyms_per_keycode_return; 

Arguments 

display  Specifies  the  display  whose  table  is  required. 

min_keycode_return 

Returns  the  minimum  keycode  valid  for  the  display. 

keysyms_per_keycode_ret urn 

Returns  the  number  of  keysyms  stored  for  each  keycode. 

Description 

The  Intrinsics  maintain  tables  internally  to  map  keycodes  to  keysyms  for  each  open  display. 
Translator  procedure  and  other  clients  may  share  a  single  copy  of  this  table  to  perform  the  same 
mapping. 

XtGetKeysymTable  returns  a  pointer  to  the  Intrinsics'  copy  of  the  server's  key- 
code-to-keysym  table.  This  table  must  not  be  modified.  The  number  of  keysyms  associated 
with  each  keycode  is  indicated  by  the  argument  keysyms_per_keycode_return.  The 
keysyms  are  located  in  the  mapping  table.  For  a  given  keycode  test_keycode,  the  table 
would  have  indices,  starting  at  index: 

(test_keycode   -  min_keycode)    *    keysyms_per_keycode_return 

Any  entries  that  have  no  keysyms  associated  with  them  contain  the  value  NoSymbol.  Clients 
should  not  cache  the  keysym  table  but  should  call  XtGetKeysymTable  each  time  the  value 
is  needed,  as  the  table  may  change  prior  to  dispatching  each  event. 

See  Also 

XtConvertCose(\\  XtKeysymToKeycodeList(\\  XtRegisterCoseConverter(l),  XtSetKeyTranslator(l), 
XfTranslateKeycode  ( 1 ). 
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XtGetMultiClickTime 

•Xt- Pointer— 

Name 

XtGetMultiClickTime  —  read  the  multi-click  time. 

Synopsis 

int  XtGetMultiClickTime (display) 
Display  *  display; 

Arguments 

display  Specifies  the  display  connection. 

Description 

XtGetMultiClickTime  returns  the  time  in  milliseconds  that  the  translation  manager  uses 
to  determine  if  multiple  events  are  to  be  interpreted  as  a  repeated  event  for  purposes  of  match 
ing  a  translation  entry  containing  a  repeat  count. 

Translation  table  entries  may  specify  actions  that  are  taken  when  two  or  more  identical  events 
occur  consecutively,  separated  by  a  short  time  interval  called  the  multi-click  time.  The  multi- 
click  time  value  can  be  specified  as  an  application  resource  with  name  multiClickTime 
and  class  MultiClickTime  and  can  also  be  modified  dynamically  by  the  application.  The 
multi-click  time  is  unique  for  each  Display  and  is  retrieved  from  the  resource  database  by  xt- 
Displaylnitialize.  If  no  value  is  specified,  the  initial  value  is  200  milliseconds. 

See  Also 

XtSetMultiClickTime(\) 
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f  XtGetResourceList 

— Xt  -  Resource  Management ' 

Name 

XtGetResourceList  —  retrieve  default  values  for  a  resource  list. 

Synopsis 

void  XtGetResourceList (object_class,  resources_return, 

num_resources_return)  ; 
WidgetClass  object_class; 
XtResourceList  *resources_return; 
Cardinal  *num_resources_return; 

Arguments 

object_class 

Specifies  the  object  class  to  be  queried;  may  be  of  class  objectClass  or  any  subclass 
thereof. 

resources_return 

Returns  the  resource  list. 

num_resources_return 

Returns  the  number  of  entries  in  the  resource  list. 

Description 

If  XtGetResourceList  is  called  before  the  widget  class  is  initialized  it  returns  the  resource 
list  as  specified  in  the  widget  class  record.  If  it  is  called  after  the  widget  class  has  been  initial 
ized,  XtGetResourceList  returns  a  merged  resource  list  that  includes  the  resources  for  all 
superclasses.  The  list  returned  by  XtGetResourceList  should  be  freed  using  xtFree 
when  it  is  no  longer  needed. 

Here  is  an  abbreviated  version  of  the  resource  list  in  the  Label  widget: 

/*  Resources  specific  to  Label  */ 
static  XtResource  resources []  =  { 
{XtNforeground,  XtCForeground,  XtRPixel,  sizeof (Pixel) , 

XtOffsetOf (LabelRec,  label . foreground) ,  XtRString, 
XtDefaultForeground} , 
{XtNfont,   XtCFont,  XtRFontStruct,  sizeof (XFontStruct  *), 

XtOffsetOf (LabelRec,  label . font) , XtRString,  XtDefaultFont } , 
{XtNlabel,   XtCLabel,  XtRString,  sizeof (String) , 

XtOffsetOf (LabelRec,  label . label) ,  XtRString,  NULL}, 


Structures 

XtResource  is  defined  as  follows  in  <X  11 /Intrinsic. h>: 

typedef  struct  _XtResource  { 

String    resource_name;   /*  Resource  name  */ 
String    resource_class;  /*  Resource  class  */ 
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(continued) 


Xt  -  Resource  Management 


String 
Cardinal 
Cardinal 
String 


resource_type; 
resource_size; 
resource_of f set ; / 
default  type; 


XtPointer  def ault_addr; 
}  XtResource,  XtResourceList; 


/*  Representation  type  desired  */ 

/*  Size  in  bytes  of  representation  */ 

Offset  from  base  to  put  resource  value  */ 
/*  Representation  type  of  specified  default  */ 
/*  Address  of  resource  default  value  */ 


See  Also 

XtFree  ( 1 ),  XtGetAppllcationResources  ( 1 ). 
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J  XtGetSelectionRequest 


Name 

XtGetSelectionRequest  — retrieve  the  Select ionRequest  event  that  triggered  the  xt- 

Convert Selection? roc. 

Synopsis 

XSelectionRequestEvent  *XtGetSelectionRequest ( w,  selection,  request_id) 
Widget  w; 
Atom  selection; 
XtRequestld  request_id; 

Arguments 

w  Specifies  the  widget  which  currently  owns  this  selection. 

selection          Specifies  the  selection  being  processed. 

request_id        Specifies  the  requestor  id  in  the  case  of  incremental  selections,  or  NULL  in  the 
case  of  atomic  transfers. 

Description 

XtGetSelectionRequest  may  only  be  called  from  within  an  xtConvertSelection- 
Proc  and  returns  a  pointer  to  the  SelectionRequest  event  which  caused  the  procedure  to 
be  invoked.  request_id  specifies  a  unique  id  for  the  individual  request  in  the  case  that  mul 
tiple  incremental  transfers  are  outstanding.  For  atomic  transfers,  request_id  must  be  speci 
fied  as  NULL.  If  no  SelectionRequest  event  is  being  processed  for  the  specified  widget, 
selection  and  reguest_id,  XtGetSelectionRequest  returns  NULL. 

See  Also 

XtGetSelectionValue(\),  XtGetSelectionValueIncremental(l),  XtGetSelectionValues(\),  XtGetSelection- 
Valueslncremental(l),  XtOwnSelection(l),  XtOwnSelectionIncremental(l). 
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XtGetSelectionTimeout  x Yt  _  , 

Xt  -  Selections- 
Name 

XtGetSelectionTimeout  —  get  the  current  selection  timeout  value. 

Synopsis 

unsigned   int   XtGetSelectionTimeout () 

Description 

XtGetSelectionTimeout  has  been  superseded  by  XtAppGetSelectionTimeout. 
XtGetSelectionTimeout  returns  the  current  value  of  the  selection  timeout  in  mil 
liseconds.  The  default  value  is  5000  milliseconds  (five  seconds). 

The  selection  timeout  is  the  time  within  which  the  two  communicating  applications  must 
respond  to  one  another.  If  one  of  them  does  not  respond  within  this  interval,  the  Intrinsics  abort 
the  selection  request. 

Chapter  10,  Interclient  Communications,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming 
Manual,  presents  a  complete  example  widget  that  both  sends  and  receives  data  using  selection. 

See  Also 

XtAppGetSelectionTimeout(l\XtAppSetSelectionTimeout(\),XtSetSelectionTimeout(l). 
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XtGetSelectionValue 


Name 

XtGetSelectionValue  —  obtain  the  complete  selection  data. 

Synopsis 

void   XtGetSelectionValue (w,    selection,    target,    callback,    cllent_data,    time) 
Widget    w; 
Atom   selection; 
Atom   target; 

Xt Select ionCallbackProc    callback; 
XtPointer   client_data; 
Time    time; 


Arguments 

w 
selection 


Specifies  the  widget  that  is  making  the  request. 

Specifies  the  particular  selection  desired  (either  XA.PRIMARY  or  XA_SEC- 
ONDARY). 
target  Specifies  the  type  to  which  the  sender  should  convert  the  selection. 

callback  Specifies  the  callback  procedure  to  be  called  when  the  selection  value  has 

been  obtained.  Note  that  this  is  how  the  selection  value  is  communicated 
back  to  the  client. 

client_data      Specifies  an  argument  to  be  passed  to  callback  when  it  is  called. 

time  Specifies  the  timestamp  that  indicates  when  the  selection  is  desired.   This 

should  be  the  timestamp  of  the  event  that  triggered  this  request;  the  value 
Cur  rent  Time  is  not  acceptable. 

Description 

XtGetSelectionValue  requests  the  selection  owner  to  send  the  value  of  the  selection, 
converted  to  the  target  type,  callback  will  be  called  some  time  after  XtGetSelection 
Value  is  called;  in  fact,  it  may  be  called  before  or  after  XtGetSelectionValue  returns. 

If  multiple  calls  to  the  server  are  required  to  get  all  the  data,  this  will  be  transparent  to  the 
widget;  the  Intrinsics  perform  all  the  necessary  fragmentation  and  reassembly  of  the  selection. 

To  determine  the  actual  target  types  that  the  selection  owner  will  be  willing  to  return,  intern  the 
string  TARGETS  using  xinternAtom,  and  send  the  corresponding  Atom  as  target. 

See  Also 

XtGetSelectionVdues(\),XtGetSelectionVcdueIncremental(\\XtOwnSelection(\), 
XtSelectionCcdlbackProc  (2). 
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XtGetSelectionValuelncremental  \ 

v Xt  -  Selections— 

Name 

XtGetSelectionValuelncremental  —  obtain  the  selection  value  using  incremental  transfers. 

Synopsis 

void  XtGetSelectionValuelncremental (w,  selection,  target,  selection  call 
back,  client_data,  time) 
Widget  w; 
Atom  selection; 
Atom  target; 

XtSelectionCallbackProc  select ion_callback; 
XtPointer  client_data; 
Time  time; 

Arguments 

w  Specifies  the  widget  that  is  making  the  request 

selection          Specifies  the  particular  selection  desired  (e.g.,  XA_PRIMARY  or  XA_SECON- 
DARY). 

target  Specifies  the  type  of  the  information  that  is  needed  about  the  selection  (e.g., 

TARGETS). 

select ion_cal Iback 

Specifies  the  callback  procedure  that  is  to  be  called  to  receive  each  data  seg 
ment 

client_data      Specifies  client-specific  data  that  is  to  be  passed  to  the  specified  callback  pro 
cedure  when  it  is  invoked. 

time  Specifies  the  timestamp  that  indicates  when  the  selection  request  was  ini 

tiated.    This  should  be  the  timestamp  of  the  event  which  triggered  this 
request;  the  value  CurrentTime  is  not  acceptable. 

Description 

When  using  the  incremental  interface,  an  owner  may  have  to  process  more  than  one  selection 
request  for  the  same  selection,  converted  to  the  same  target,  at  the  same  time.  The 
request_id  argument  is  guaranteed  to  be  unique  among  all  incremental  requests  that  are 
active  concurrently. 

XtGetSelectionValuelncremental  is  similar  to  XtGetSelectionValue  except 
that  the  select ion_callback  procedure  will  be  called  repeatedly  upon  delivery  of  multi 
ple  segments  of  the  selection  value.  The  end  of  the  selection  value  is  indicated  when  selec- 
tlon_callback  is  called  with  a  non-NULL  value  of  length  zero,  which  must  still  be  freed  by 
the  client.  If  the  transfer  of  the  selection  is  aborted  in  the  middle  of  a  transfer  (for  example,  due 
to  timeout),  the  selection_callback  procedure  is  called  with  a  type  of  XT_CON- 
VERT_FAIL  so  that  the  requestor  can  dispose  of  the  partial  selection  value  it  has  collected  up 
until  that  point.  Upon  receiving  XT_CONVERT_FAIL,  the  requesting  client  must  determine  for 
itself  whether  or  not  a  partially  completed  data  transfer  is  meaningful. 
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(continued)    XtGetSelectionValuelncremental 


See  Also 

XtGetSelectionValue  ( 1 ),  XtGetSelectionValuesIncremental  ( 1 ),  XtOwnSelectionlncremental  ( 1 ). 
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XtGetSelectionValues  A 


•Xt-  Selections — 


Name 

XtGetSelectionValues  —  obtain  selection  data  in  multiple  formats. 

Synopsis 

void  XtGetSelectionValues (w,  selection,  targets,  count,  callback,  cli- 

ent_data,  time) 
Widget  w; 
Atom  selection; 
Atom  *  targets; 
int  count; 

Xt Select ionCallbackProc  callback; 
XtPointer  client_data; 
Time  time; 

Arguments 

w  Specifies  the  widget  that  is  making  the  request. 

selection          Specifies  the  particular  selection  desired  either  XA_PRIMARY  or  XA_SECON- 
DARY. 

targets  Specifies  the  types  to  which  the  sender  should  convert  the  selection. 

count  Specifies  the  length  of  the  targets  and  client_data  lists. 

callback  Specifies  the  callback  procedure  to  be  called  with  each  selection  value 

obtained.  Note  that  this  is  how  the  selection  values  are  communicated  back 
to  the  client. 

client_data      Specifies  the  client  data  (one  for  each  target  type)  that  is  passed  to  the 
callback  procedure  when  it  is  called  for  that  target. 

time  Specifies  the  timestamp  that  indicates  when  the  selection  value  is  desired. 

This  should  be  the  timestamp  of  the  event  that  triggered  this  request;  the 
value  CurrentTime  is  not  acceptable. 

Description 

XtGetSelectionValues  is  similar  to  XtGetSelectionValue  except  that  it  takes  a  list 
of  target  types  and  a  list  of  client  data  and  obtains  the  current  value  of  the  selection  converted 
to  each  of  the  targets.  The  effect  is  as  if  each  target  were  specified  in  a  separate  call  to  xt  - 
GetSelectionValue.  The  callback  is  called  once  with  the  corresponding  client  data  for 
each  target.  XtGetSelectionValues  guarantees  that  all  the  conversions  will  use  the  same 
selection  value  because  the  ownership  of  the  selection  cannot  change  in  the  middle  of  the  list, 
as  could  happen  when  calling  XtGetSelectionValue  repeatedly. 

To  determine  the  actual  target  types  that  the  selection  owner  will  be  willing  to  return,  intern  the 
string  TARGETS,  and  send  the  corresponding  Atom  as  target. 
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(continued) 


XtGetSelectionValues 


Chapter  10,  Interdient  Communications,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming 
Manual,  presents  a  complete  example  widget  that  both  sends  and  receives  data  using  selection. 

See  Also 

XtGetSelectionValue  ( 1 ),  XtGetSelectionValuelncremental  ( 1 ),  XtOwnSelection  ( 1 ), 
XtSelectionCallbackProc(T). 
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XtGetSelectionValueslncrementalX 


•  Xt-  Selections- 


Name 

XtGetSelectionValuesIncremental  —  obtain  multiple  selection  values  using  incremental 

transfers. 

Synopsis 

void  XtGetSelectionValuesIncremental ( w,  selection,  targets,  count,  selec- 

tion_callback,  client_data,  time) 
Widget  w; 
Atom  selection; 
Atom  *  targets; 
int  count; 

Xt Select ion I ncr Callback? roc  select ion_callback; 
XtPointer  * client_data; 
Time  time; 

Arguments 

w  Specifies  the  widget  that  is  making  the  request. 

selection          Specifies  the  particular  selection  desired  (e.g.,  XA_PRIMARY  or  XA_SEC- 
ONDARY). 

targets  Specifies  the  types  of  information  that  is  needed  about  the  selection  (e.g., 

HOST,  USER). 

count  Specifies  the  length  of  the  targets  and  client_data  lists. 

select ion_cal Iback 

Specifies  the  callback  procedure  that  is  to  be  called  to  receive  each  selection 
value. 

dlent_data      Specifies  a  list  of  client  data  (one  for  each  target  type)  that  is  passed  to  the 
callback  procedures  when  they  are  invoked  for  the  corresponding  target. 

time  Specifies  the  timestamp  that  indicates  when  the  selection  request  was  ini 

tiated.    This  should  be  the  timestamp  of  the  event  which  triggered  this 
request;  the  value  CurrentTime  is  not  acceptable. 

Description 

XtGetSelectionValuesIncremental  is  similar  to  XtGetSelectionValue- 
Incremental  except  that  the  former  takes  a  list  of  targets  and  client_data.  XtGet- 
SelectionValuesIncremental  is  equivalent  to  calling  XtGetSelectionValue- 
Incremental  successively  for  each  target/client_data  pair  except  that  XtGet- 
SelectionValueslncremental  guarantees  that  all  the  conversions  will  use  the  same 
selection  value  because  the  ownership  of  the  selection  cannot  change  in  the  middle  of  the  list, 
as  would  be  possible  when  calling  xtGetSelectionValuelncremental  repeatedly. 

See  Also 

XtGetSelectionValue(l)tX^etSelectionVolueIncremenIal(l),XtOwnSelectionIncremental(l). 
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— Xt  -  Resource  Management ' 

Name 

XtGetSubresources  —  update  subpart  resource  list. 

Synopsis 

void  XtGetSubresources (object,  base,  name,  class,  resources,  num_resources, 

args,  num__args) 
Widget  object; 
XtPointer  base; 
String  name; 
String  class; 
XtResourceList  resources; 
Cardinal  /)u/n_resources; 
ArgList  args; 
Cardinal  num_args; 

Arguments 

object  Specifies  the  object  used  to  qualify  the  subpart  resource  name  and  class;  may 

be  of  class  Object  or  any  subclass  thereof. 

base  Specifies  the  base  address  of  the  subpart  data  structure  where  the  resources 

will  be  written. 

name  Specifies  the  name  of  the  subpart. 

class  Specifies  the  class  of  the  subpart. 

resources          Specifies  the  resource  list  for  the  subpart. 

nu/n_resources  Specifies  the  number  of  resources  in  the  resource  list. 

args  Specifies  the  argument  list  to  override  any  other  resource  specifications. 

num_args  Specifies  the  number  of  arguments  in  the  argument  list. 

Description 

A  widget  does  not  do  anything  to  get  its  own  resources;  instead,  xtCreateWidget  does  this 
automatically  before  calling  the  class  initialize  procedure. 

However,  some  widgets  have  subparts  that  are  not  widgets  but  for  which  the  widget  would  like 
to  fetch  resources.  For  example,  the  R3  Athena  Text  widget  fetched  resources  for  its  source 
and  sink.  Such  widgets  call  XtGetSubresources  to  accomplish  this.  (Text  now  uses 
objects  instead  of  subparts.) 

XtGetSubresources  constructs  a  name  or  class  list  from  the  application  name  or  class,  the 
names  or  classes  of  all  its  ancestors,  and  the  widget  itself.  Then,  it  appends  to  this  list  the  name 
or  class  pair  passed  in.  resources  is  fetched  from  the  argument  list,  the  resource  database, 
or  the  default  values  in  the  resource  list.  Then,  resources  is  copied  into  the  subpart  record. 
If  args  is  NULL,  num_args  must  be  zero.  However,  if  num_args  is  zero,  the  argument  list 
is  not  referenced. 

XtGetSubresources  may  overwrite  the  specified  resource  list  with  an  equivalent  represen 
tation  in  an  internal  format  that  optimizes  access  time  if  the  list  is  used  repeatedly.  The 
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resource  list  must  be  allocated  in  writable  storage  and  the  caller  must  not  modify  the  list  con 
tents  after  the  call  if  the  same  list  is  to  be  used  again.  Resources  fetched  by  xtGet- 
Subresources  are  reference  counted  as  if  they  were  referenced  by  the  specified  widget. 
Subresources  might  therefore  be  freed  from  the  conversion  cache  and  destroyed  when  the 
widget  is  destroyed,  but  not  before  then. 

With  the  exception  of  name  and  class,  the  arguments  to  xtGetSubresources  are  the 
same  as  those  for  XtGetApplicationResources.  See  XtGetApplication- 
Resources  for  additional  details. 

All  resource-fetching  routines  (XtGetSubresources  and  XtGetApplication 
Resources)  call  resource  converters  if  the  desired  representation  differs  from  the  resource 
the  user  specifies  or  from  the  widget's  default  resource  value. 

For  more  information,  see  Chapter  9,  Resource  Management  and  Type  Conversion,  in  Volume 
Four,  X  Toolkit  Intrinsics  Programming  Manual. 

Structures 

xtResource  is  defined  as  follows  in  <X 11  /Intrinsic. h>: 

typedef   struct   _XtResource    { 

String  resource_name;       /*    Resource   name    */ 

String  resource_class;    /*    Resource   class    */ 

String          resource_type;      /*    Representation   type   desired    */ 

Cardinal      resource_size;       /*    Size    in  bytes   of   representation    */ 

Cardinal      resource_of f set; /*   Offset    from  base   to  put    resource   value    */ 

String          def ault_type;         /*    Representation   type   of   specified   default    */ 

XtPointer   default_addr;         /*   Address   of   resource   default   value    */ 

}    XtResource,    XtResourceList ; 

An  Arg  is  defined  as  follows: 

typedef  struct  { 

String  name; 

XtArgVal   value; 
}    Arg,    *ArgList; 

See  Also 

XtGetApplicationResources  ( 1 ),  XtVaGetSubresources  ( 1 ). 
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XtGetSubvalues 


Name 

XtGetSubvalues  —  copy  from  subpart  data  structure  to  the  argument  list. 

Synopsis 

void  XtGetSubvalues (base,  resources,  num_resources,  args,  num_args) 
XtPointer  base; 
XtResourceList  resources; 
Cardinal  nu/n_resources; 
ArgList  args; 
Cardinal  num_args; 


Arguments 

base 


Specifies  the  base  address  of  the  subpart  data  structure  for  which  the 
resources  should  be  retrieved. 


resources          Specifies  the  nonwidget  resource  list. 
/7u/n_resources  Specifies  the  number  of  resources  in  the  resource  list. 


args 


num  args 


Specifies  the  argument  list  of  name/address  pairs  that  contain  the  resource 
names  and  the  addresses  into  which  the  resource  values  are  to  be  stored.  The 
arguments  and  the  values  that  are  passed  in  depend  on  the  subpart.  The  stor 
age  for  argument  values  that  are  pointed  to  by  the  argument  list  must  be  deal 
located  by  the  application  when  no  longer  needed. 

Specifies  the  number  of  arguments  in  the  argument  list. 


Description 

XtGetSubvalues  obtains  resource  values  from  the  structure  identified  by  base,  and  writes 
them  in  the  provided  argument  list.  XtGetSubvalues  expects  the  contents  of  args  to  be 
pointers  to  locations  where  the  actual  values  can  be  put. 

The  conjugate  function  xtSetSubvalues  sets  a  widget's  values. 

XtGetSubvalues  is  used  for  obtaining  resource  data  from  entities  that  are  not  widgets.  For 
further  discussion  of  nonwidget  subclass  resources,  see  xtGetSubresources. 

XtGetSubvalues  is  normally  called  in  the  get_values_hook  method  of  a  widget  with  a 
subpart.  It  can  never  be  called  from  the  application  because  the  application  does  not  have  the 
subpart  resource  list. 

Structures 

XtResource  is  defined  as  follows  in  <Xll/Intrinsic.h>: 


typedef   struct      XtResource    { 


String 

String 

String 

Cardinal 

Cardinal 

String 


resource_name; 
resource_class; 
resource_type ; 
resource   size; 


Resource   name    */ 
Resource   class    */ 
Representation   type   desired    */ 
Size   in  bytes   of   representation    */ 
resource_of fset;/*   Offset    from  base   to  put    resource   value    */ 
default   type;         /*    Representation   type   of   specified   default    */ 
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XtPointer   default_addr;         /*   Address   of   resource   default   value    */ 
}    XtResource,    XtResourceList; 

An  Arg  is  defined  as  follows: 

typedef   struct    { 

String   name; 

XtArgVal   value; 
}    Arg,    *ArgList; 

See  Also 

XtSetArgd),  XtVaGetSubvalues(l), 
get_values_hook(4),  initialize _hook(4). 
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Name 

XtGet Values  —  copy  resources  from  a  widget  to  the  argument  list. 

Synopsis 

void  XtGetValues (object,  args,  num_args) 
Widget  object; 
ArgList  args; 
Cardinal  num_args; 

Arguments 

object  Specifies  the  object  whose  resource  values  are  to  be  returned;  may  be  of  class 

Object  or  any  subclass  thereof. 

args  Specifies  the  argument  list  of  name/address  pairs  that  contain  the  resource 

names  and  the  addresses  into  which  the  resource  values  are  to  be  stored.  The 
resource  names  are  widget-dependent. 

num_args  Specifies  the  number  of  arguments  in  the  argument  list. 

Description 

XtGetValues  retrieves  the  current  values  of  one  or  more  resources  associated  with  a  widget 
instance.  The  conjugate  function  xtSetValues  sets  a  widget's  resource  values. 

The  name  fields  in  args  contain  the  names  of  resources.  The  value  fields  in  args  contain 
addresses  into  which  XtGetValues  stores  the  corresponding  resource  values.  XtGet 
Values  expects  the  args  .value  fields  to  be  pointers  to  locations  where  the  actual  values 
can  be  put  It  is  the  caller's  responsibility  to  allocate  and  deallocate  this  storage  according  to 
the  size  of  the  resource  representation  type  used  within  the  widget. 

XtGetValues  starts  with  the  resources  specified  for  the  Core  widget  fields  and  descends  the 
subclass  chain  to  the  widget  If  the  widget's  parent  is  a  subclass  of  const raintwidget- 
Class,  XtGetValues  then  fetches  the  values  for  any  Constraint  resources  requested.  It 
starts  with  the  Constraint  resources  specified  for  constraintwidgetClass  and  proceeds 
down  the  subclass  chain  to  the  parent's  Constraint  resources.  If  the  argument  list  contains  a 
resource  name  that  is  not  found  in  any  of  the  resource  lists  searched,  the  value  at  the  corre 
sponding  address  is  not  modified. 

If  any  get_values_hook  methods  in  the  widget's  class  or  superclass  records  are  non-NULL, 
they  are  called  in  superclass-to-subclass  order  after  all  the  resource  values  have  been  fetched 
by  XtGetValues.  Finally,  XtGetValues  calls  the  get_values_hook  method  in  super 
class-to-subclass  order.  If: 

•  The  widget's  parent  is  a  subclass  of  constraintwidgetClass  any  of  the  parent's 
class  or  superclass  records  have  declared  ConstraintClassExtension  records  in  the 
constraint  class  part  extension  fields  with  a  record  type  of  NULLQUARK  the  get_val- 
ues_hook  field  in  the  extension  record  is  non-NULL. 

•  Calling  the  get_values_hook  methods  permits  a  subclass  and  constraint  parent  to  pro 
vide  nonwidget  resource  data  to  XtGetValues. 
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Structures 

An  Arg  is  defined  as  follows  in  <X1  II Intrinsic. h>: 

typedef  struct  { 

String  name; 

XtArgVal   value; 
}    Arg,    *ArgList; 

See  Also 

XtSetArg(l),  XtSetValues(l),  XtVaGetValues(l\  XtVaSetValues(l), 
get_yalues_hook  (4),  initialize _hook(4). 
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XtGrabButton 


Name 

XtGrabButton  —  passively  grab  a  single  pointer  button. 

Synopsis 

void  XtGrabButton (widget,  button,  modifiers,  owner_events,  event_mask, 

pointer_mode,  keyboard_mode,  confine_to,  cursor) 
Widget  widget; 
int  button; 
Modifiers  modifiers; 
Boolean  owner_events; 
unsigned  int  event_mask; 
int  pointer_mode,  keyboard_mode; 
Window  confine_to; 
Cursor  cursor; 

Arguments 

wi  dget  Specifies  the  widget  in  whose  window  the  button  is  to  be  grabbed. 

button  Specifies  the  mouse  button.  May  be  Buttonl,  Button2, Buttons, But - 

ton4,  Buttons,  or  AnyButton.  The  constant  AnyButton  is  equivalent 
to  issuing  the  grab  request  for  all  possible  buttons.  The  button  symbols  can 
not  be  ORed. 

modifiers  Specifies  a  set  of  keymasks.  This  is  a  bitwise  OR  of  one  or  more  of  the  fol 
lowing  symbols:  ShiftMask,  LockMask,  ControlMask,  ModlMask, 
Mod2Mask,  ModSMask,  Mod4Mask,  ModSMask,  or  AnyModifier. 
AnyModif  ier  is  equivalent  to  issuing  the  grab  key  request  for  all  possible 
modifier  combinations  (including  no  modifiers). 

grab_window     Specifies  the  ID  of  the  window  you  want  to  the  grab  to  occur  in. 

owner_e vents    Specifies  a  Boolean  value  of  either  True  or  False.  See  Description  below. 

event_mask  Specifies  the  event  mask  to  take  effect  during  the  grab.  This  mask  is  the  bit 
wise  OR  of  one  or  more  of  the  event  masks  listed  on  the  reference  page  for 
XSelectlnput. 

point er_mode  Controls  processing  of  pointer  events  during  the  grab.  Pass  one  of  these  con 
stants:  GrabModeSync  or  GrabModeAsync. 

keyboard_mode  Controls  processing  of  keyboard  events  during  the  grab.  Pass  one  of  these 
constants:  GrabModeSync  or  GrabModeAsync. 

confine_to  Specifies  the  ID  of  the  window  to  confine  the  pointer.  One  possible  value  is 
the  constant  None,  in  which  case  the  pointer  is  not  confined  to  any  window. 

cursor  Specifies  the  cursor  to  be  displayed  during  the  grab.  One  possible  value  you 

can  pass  is  the  constant  None. 

Description 

XtGrabButton  calls  XGrabButton  specifying  the  widget's  window  as  the  grab  window,  if 
the  widget  is  realized.   The  remaining  arguments  are  exactly  as  for  XGrabButton.  If  the 
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widget  is  not  realized,  or  is  later  unrealized,  the  call  to  XGrabButton  will  be  performed 
(again)  when  the  widget  is  realized  and  its  window  becomes  mapped.  In  the  future,  if  a 
ButtonPress  event  matching  the  specified  button  and  modifiers  (which  may  be  Any- 
Button  and/or  AnyModif  ier,  respectively)  arrives  for  the  widget's  window  and  there  is  a 
modal  cascade  and  the  widget  is  not  in  the  active  subset  of  the  cascade  and  the  pointer  was  not 
previously  grabbed,  then  the  Intrinsics  will  call  xtUngrabPointer  with  the  timestamp  from 
the  ButtonPress  event 

See  Also 

XtAddGrab(\),  XtGrabKey(\\  XtGrabKeyboard(\\  XtGrabPointer(l),  XtRegisterGrabAction(\\  Xt- 
UngrabButton(l),  XtUngrabKey(\\  XtUngrabKeyboard(\),  XtUngrabPointer (1). 
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XtGrabKey 


Name 

XtGrabKey  —  passively  grab  a  single  key  of  the  keyboard. 

Synopsis 

void  XtGrabKey  (widget,  keycode,  modifiers,  owner_events,  pointer_mode,  key- 

board_mode) 
Widget  widget; 
KeyCode  keycode; 
Modifiers  modifiers; 
Boolean  owner_events; 
int  pointer_mode,  keyboard_mode; 

Arguments 

widget  Specifies  the  widget  in  whose  window  the  key  is  to  be  grabbed. 

keycode  Specifies  the  keycode  to  be  grabbed.  It  may  be  a  modifier  key.  Specifying 

AnyKey  is  equivalent  to  issuing  the  request  for  all  key  codes. 

modi  fi  ers  Specifies  a  set  of  keymasks.  This  is  a  bitwise  OR  of  one  or  more  of  the  fol 
lowing  symbols:  ShiftMask,  LockMask,  Control  Mask,  ModlMask, 
Mod2Mask,  Mod3Mask,  Mod4Mask,  ModSMask,  or  AnyModifier. 
AnyModif  ier  is  equivalent  to  issuing  the  grab  key  request  for  all  possible 
modifier  combinations  (including  no  modifiers).  All  specified  modifiers  do 
not  need  to  have  currently  assigned  keycodes. 

grab_window  Specifies  the  window  in  which  the  specified  key  combination  will  initiate  an 
active  grab. 

owner_ events  Specifies  whether  the  grab  window  should  receive  all  events  (True)  or 
whether  the  grabbing  application  should  receive  all  events  normally 
(False). 

pointer_mode  Controls  processing  of  pointer  events  during  the  grab.  Pass  one  of  these  con 
stants:  GrabModeSync  or  GrabModeAsync. 

keyboard_mode  Controls  processing  of  keyboard  events  during  the  grab.  Pass  one  of  these 
constants:  GrabModeSync  or  GrabModeAsync. 

Description 

XtGrabKey  calls  XGrabKey  specifying  the  widget's  window  as  the  grab  window  if  the 
widget  is  realized.  The  remaining  arguments  are  exactly  as  for  XGrabKey.  If  the  widget  is 
not  realized,  or  is  later  unrealized,  the  call  to  XGrabKey  will  be  performed  (again)  when  the 
widget  is  realized  and  its  window  becomes  mapped.  In  the  future,  if  a  Key  Press  event 
matching  the  specified  keycode  and  modifiers  (which  may  be  AnyKey  and/or  AnyModifier, 
respectively)  arrives  for  the  widget's  window  and  there  is  a  modal  cascade  and  the  widget  is 
not  in  the  active  subset  of  the  cascade  and  the  keyboard  was  not  previously  grabbed,  then  the 
Intrinsics  will  call  xtUngrabKeyboard  with  the  timestamp  from  the  KeyPress  event. 


X  Toolkit  Intrinsics  Reference  Manual 


209 


XtGrabKey  (continued)  Xt  -  Keyboard  Handling 

See  Also 

XtAddGrab(\),  XtGrabButton(\\  XtGrabKeyboard(\),  XtGrabPointer(\\  XtRegisterGrabAction(\\  Xt- 
UngrabButton(\\  XtUngrabKey(\\  XtUngrabKeyboard(\),  XtUngrabPointer(\). 


210  X  Toolkit  Intrinsics  Reference  Manual 


j  XtGrabKey  board 

— Xt  -  Keyboard  Handling ' 

Name 

XtGrabKeyboard  —  actively  grab  the  keyboard. 

Synopsis 

int  XtGrabKeyboard (widget,  owner_events,  pointer_mode,  keyboard_mode ,  time) 
Widget  widget; 
Boolean  owner_events; 
int  pointer_mode,  keyboard_mode; 
Time  time; 

Arguments 

wi  dget  Specifies  the  widget  for  whose  window  the  keyboard  is  to  be  grabbed. 

owner_ events    Specifies  a  Boolean  value  of  either  True  or  False.  See  Description  below. 

pointer_mode    Controls  processing  of  pointer  events  during  the  grab.  Pass  either  Grab- 
ModeSync  or  GrabModeAsync. 

keyboard_mode  Controls  processing  of  keyboard  events  during  the  grab.  Pass  either  Grab- 
ModeSync  or  GrabModeAsync. 

time  Specifies  the  time  when  the  grab  should  take  place.  Pass  either  a  timestamp, 

expressed  in  milliseconds,  or  the  constant  CurrentTime. 

Description 

If  the  specified  widget  is  realized  XtGrabKeyboard  calls  XGrabKeyboard  specifying  the 
widget's  window  as  the  grab  window.  The  remaining  arguments  and  return  value  are  exactly  as 
for  XGrabKeyboard.  If  the  widget  is  not  realized,  XGrabKeyboard  immediately  returns 
GrabNotViewable.  No  future  automatic  ungrab  is  implied  by  XtGrabKeyboard. 

See  Also 

XtAddGrab(l\  XtGrabButton(\\  XtGrabKey  (1),  XtGrabPointer(l\  XtRegisterGrabAction(l),  Xt- 
UngrabButton(l),  XtUngrabKey(l),  XtUngrabKeyboard(\\  XtUngrabPoinler(\}. 
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•  Xt- Pointer— 


Name 

XtGrabPointer  —  actively  grab  the  pointer. 

Synopsis 

int  XtGrabPointer  ( widget,  owner_events,  event_mask,  point er_mode,  key- 

board_mode,  confine_to,  cursor,  time) 
Widget  widget; 
Boolean  owner_events; 
unsigned  int  event_mask; 
int  pointer_mode,  keyboard_mode; 
Window  confine_to; 
Cursor  cursor; 
Time  time; 

Arguments 

widget  Specifies  the  widget  for  whose  window  the  pointer  is  to  be  grabbed. 

owner_events  Specifies  if  the  pointer  events  are  to  be  reported  normally  within  this  applica 
tion  (pass  True)  or  only  to  the  grab  window  (pass  False). 

event_mask  Specifies  the  event  mask  symbols  that  can  be  ORed  together.  Only  events 
selected  by  this  mask,  plus  ButtonPress  and  ButtonRelease,  will  be 
delivered  during  the  grab.  See  XSelect Input  for  a  complete  list  of  event 
masks. 

pointer_mode  Controls  further  processing  of  pointer  events.  Pass  either  GrabModeSync 
or  GrabModeAsync. 

keyboard_mode  Controls  further  processing  of  keyboard  events.  Pass  either  GrabModeSync 

or  GrabModeAsync. 

confine_to  Specifies  the  ID  of  the  window  to  confine  the  pointer.  One  option  is  None,  in 
which  case  the  pointer  is  not  confined  to  any  window. 

cursor  Specifies  the  ID  of  the  cursor  that  is  displayed  with  the  pointer  during  the 

grab.  One  option  is  None,  which  causes  the  cursor  to  keep  its  current  pattern. 

time  Specifies  the  time  when  the  grab  request  took  place.  Pass  either  a  timestamp, 

expressed  in  milliseconds  (from  an  event),  or  the  constant  CurrentTime. 

Description 

If  the  specified  widget  is  realized,  XtGrabPointer  calls  XGrabPointer  specifying  the 
widget's  window  as  the  grab  window.  The  remaining  arguments  and  return  value  are  exactly  as 
for  XGrabPointer.  If  the  widget  is  not  realized,  XGrabPointer  immediately  returns 
GrabNotViewable.  No  future  automatic  ungrab  is  implied  by  XtGrabPointer. 

See  Also 

XtAddGrab(l),  XtGrabButton(\),  XtGrabKey(l\  XtGrabKeyboard(\\  XtRegisterGrabAction(\\  Xt- 
UngrabButton(l),  XtUngrabKey(l\  XtUngrabKeyboard(\\  XtUngrabPointer(\). 
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J  XtHasCallbacks 


Name 

XtHasCallbacks  —  determine  the  status  of  a  widget's  callback  list. 

Synopsis 

XtCallbackStatus  XtHasCallbacks (object,  callback_name) 
Widget  object; 
String  callback_name; 

Arguments 

object  Specifies  the  object;  may  be  of  class  Object  or  any  subclass  thereof. 

cal lback_name       Specifies  the  callback  list  to  be  checked. 

Description 

XtHasCallbacks  checks  the  widget  for  a  resource  named  callback_name.  If  the 
resource  does  not  exist  or  is  not  of  type  xtRCallback,  XtHasCallbacks  returns  xt- 
CallbackNoList.  If  the  callback  list  exists  but  is  empty,  it  returns  xtCallbackHas- 
None.  If  the  callback  list  contains  at  least  one  callback  procedure,  it  returns  xtCallback- 
HasSome. 

Structures 

typedef  enum  { 

XtCallbackNoList, 

XtCallbackHasNone, 

XtCallbackHasSome 
}  XtCallbackStatus; 

See  Also 

XtAddCallbacks(\\  XtCallCallbacks(\),  XtCallCallbackList(\). 
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v Xt  -  Initialization— 

Name 

Xtlnitialize  —  initialize  toolkit  and  display. 

Synopsis 

Widget  Xtlnitialize (shell_name,  application_class,  options,  num_options, 

argc,  argv) 

char  *shell_name;  /*unused  in  R3*/ 
char  *application_class; 
XrmOptionDescRec  options[] ; 
Cardinal  num_options; 
Cardinal  * argc; 
char  *argv[ ]  ; 

Arguments 

shell_name        Specifies  the  name  of  the  application  shell  widget  instance. 

application_class 

Specifies  the  class  name  of  this  application. 

options  Specifies   how  to  parse   the  command  line   for  any   application-specific 

resources.  The  options  argument  is  passed  as  a  parameter  to  XrmParse- 
Command. 

num_options      Specifies  the  number  of  entries  in  options  list. 

argc  Specifies  a  pointer  to  the  number  of  command  line  parameters. 

argv  Specifies  the  command  line  parameters.  , 

Description 

Xtlnitialize  has  been  superseded  by  XtApplnitialize.  Xtlnitialize  returns  an 
application  shell  suitable  for  parenting  the  rest  of  the  application,  and  consolidates  other  requi 
site  Toolkit  initialization.  This  is  the  initialization  routine  of  choice  for  simple  applications  that 
use  widgets. 

Xtlnitialize  calls  XtToolkitlnitialize  to  initialize  the  Toolkit  internals,  creates  a 
default  application  context  with  XtCreateApplicationContext,  xtOpenDisplay, 
and  XtAppCreateShell,  and  returns  the  created  shell.  Xtlnitialize  is  generally  more 
convenient  than  calling  each  of  the  routines  individually. 

The  semantics  of  calling  Xtlnitialize  more  than  once  are  undefined. 
Command  Line  Parsing 

Xtlnitialize  calls  XtDisplaylnitialize,  which  in  turn  calls  the  Xlib  XrmParse- 
Command  function  to  parse  the  command  line. 

The  command  line  parser  modifies  argc  and  argv  to  contain  only  those  parameters  that  were 
not  in  the  standard  option  table  or  in  the  table  specified  by  the  options  argument.  If  the 
resulting  argc  is  not  zero,  then  there  were  unexpected  parameters  declared  on  the  user's  com 
mand  line.  Most  applications  handle  this  by  simply  printing  out  the  remaining  contents  of 


214  X  Toolkit  Intrinsics  Reference  Manual 


Xt- Initialization  (continued)  Xtlnitialize 

argrv  along  with  a  message  listing  the  allowable  options,  with  the  application  name.  (On 
POSDC-based  systems,  the  application  name  is  usually  the  final  component  of  argv  [  0  ] .) 

Note  that  the  argc  and  argv  arguments  of  Xtlnitialize  are  in  the  same  order  as  in  the 
call  to  main.  This  is  the  opposite  order  of  arrays  and  array  lengths  throughout  other  Xt  and 
Xlib  routine  calls.  Also  note  that  the  address  of  argc,  not  argc  itself,  is  passed  to  Xt 
lnitialize.  This  is  so  that  Xtlnitialize  can  decrement  the  count  to  reflect  recognized 
options.  Watch  out  for  these  snags. 

Loading  the  Resource  Database 

The  XtDisplaylnitialize  function  loads  the  application's  resource  database  for  this  dis 
play/host/application  combination  from  the  following  sources  (in  order): 

•  Application-specific  class  resource  file  on  the  local  host. 

•  Application-specific  user  resource  file  on  the  local  host. 

•  Resource  property  on  the  server  or  user  preference  resource  file  on  the  local  host. 

•  Per-host  user  environment  resource  file  on  the  local  host, 

•  Application  command  line  (argv). 

Each  resource  database  is  kept  on  a  per-display  basis. 

The  application-specific  class  resource  file  name  is  constructed  from  the  class  name  of  the 
application.  It  points  to  a  site-specific  resource  file  that  usually  is  installed  by  the  site  manager 
when  the  application  is  installed.  On  POSDC-based  systems,  this  file  usually  is  lusrlliblXlllapp- 
defaults/ class,  where  class  is  the  application  class  name.  This  file  is  expected  to  be  provided  by 
the  developer  of  the  application  and  may  be  required  for  the  application  to  function  properly. 

The  application-specific  user  resource  file  name  is  constructed  from  the  class  name  of  the  appli 
cation  and  points  to  a  user-specific  resource  file.  This  file  is  owned  by  the  application  and  typi 
cally  stores  user  customizations.  On  POSDC-based  systems,  this  file  name  is  constructed  from 
the  user's  XAPPLRESDIR  variable  by  appending  class  to  it,  where  class  is  the  application  class 
name.  (That  is,  XAPPLRESDIR  specifies  the  name  of  a  directory,  and  class  the  name  of  a  file 
contained  in  it)  If  XAPPLRESDIR  is  not  defined,  it  defaults  to  the  user's  home  directory.  If  the 
resulting  resource  file  exists,  it  is  merged  into  the  resource  database.  This  file  may  be  provided 
with  the  application  or  constructed  by  the  user. 

The  server  resource  file  is  the  contents  of  the  X  server's  RESOURCE_MANAGER  property  that 
was  returned  by  XOpenDi splay.  If  no  such  property  exists  for  the  display,  the  contents  of 
the  resource  file  in  the  user's  home  directory  is  used  instead.  On  POSDC-based  systems,  the 
usual  name  for  the  user  preference  resource  file  is  Xdefaidts.  If  the  resulting  resource  file 
exists,  it  is  merged  into  the  resource  database.  The  server  resource  file  is  constructed  entirely 
by  the  user  and  contains  both  display-independent  and  display-specific  user  preferences. 

If  one  exists,  a  user's  environment  resource  file  is  then  loaded  and  merged  into  the  resource 
database.  This  file  name  is  user  and  host  specific.  On  POSDC-based  systems,  the  user's  environ 
ment  resource  file  name  is  constructed  from  the  value  of  the  user's  XENVIRONMENT  variable 
for  the  full  path  of  the  file.  If  this  environment  variable  does  not  exist,  XtDisplay 
lnitialize  searches  the  user's  home  directory  for  the  Xdefaults-host  file,  where  host  is  the 
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name  of  the  machine  on  which  the  application  is  running.  If  the  resulting  resource  file  exists,  it 
is  merged  into  the  resource  database.  The  environment  resource  file  is  expected  to  contain 
system-specific  resource  specifications  that  are  to  supplement  those  user-preference  specifica 
tions  in  the  server  resource  file. 

Parsing  the  Command  Line 

XtDi  splay  Initialize  has  a  table  of  standard  command  line  options  for  adding  resources 
to  the  resource  database,  and  it  can  accept  application-specific  resource  abbreviations. 

The  format  of  this  table  is  shown  below  in  the  Structures  section  of  this  reference  page.  The 
standard  table  contains  the  following  entries: 


Option 

Resource 

Value 

Sets 

-background 

*background 

next  argument 

background  color 

-bd 

*borderColor 

next  argument 

border  color 

-bg 

*background 

next  argument 

background  color 

-bordercolor 

*borderColor 

next  argument 

color  of  border 

-borderwidth 

.borderWidth 

next  argument 

width  of  border  in  pixels 

-bw 

.borderWidth 

next  argument 

width  of  border  in  pixels 

-display 

.display 

next  argument 

server  to  use 

-fg 

*  foreground 

next  argument 

foreground  color 

-fn 

*font 

next  argument 

font  name 

-font 

*font 

next  argument 

font  name 

-foreground 

^foreground 

next  argument 

foreground  color 

-geometry 

.geometry 

next  argument 

size  and  position 

-iconic 

.  iconic 

"on" 

start  as  an  icon 

-name 

.name 

next  argument 

name  of  application 

-reverse 

*  re  verse  Video 

"on" 

reverse  video 

-rv 

*reverseVideo 

"on" 

reverse  video 

+rv 

*reverseVideo 

"off 

No  Reverse  Video 

-selectionTimeout 

.  selectionTimeout 

Null 

selection  timeout 

-synchronous 

.  synchronous 

"on" 

synchronous  debug  mode 

asynchronous 

.  synchronous 

"off1 

synchronous  debug  mode 

-title 

.title 

next  argument 

titie  of  application 

-xnlLanguage 

.xnlLanguage 

next  argument 

language 

-xrm 

value  of  argument 

next  argument 

depends  on  argument 

Note  that  any  unique  abbreviation  for  an  option  name  in  the  standard  table  or  in  the  application 
table  is  accepted. 

The  table  above  lists  the  complete  set  of  standard  options.  Options  for  which  the  resource 
name  is  shown  starting  with  a  dot  rather  than  an  asterisk  set  that  resource  only  in  the  applica 
tion's  top-level  Shell. 

If  the  user  specifies  synchronize  True  on  the  command  line,  XtDisplaylnitialize 
calls  the  Xlib  XSynchronize  function  to  put  the  Xlib  display  connection  into  synchronous 
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mode.  If  reverseVideo  is  True,  the  Intrinsics  exchange  XtDef  aultForeground  and 
XtDef  aultBackground  for  widgets  created  on  this  display. 

The  -xrm  option  provides  a  method  of  setting  any  resource  in  an  application.  The  next  argu 
ment  should  be  a  quoted  string  identical  in  format  to  a  line  in  the  user  resources  file.  For 
example,  to  give  a  red  background  to  all  command  buttons  in  an  application  named  xmh,  you 
can  start  it  up  as: 

xmh  -xrm  ' xmh*Command. background:  red' 

When  it  fully  parses  the  command  line,  XtDisplaylnitialize  merges  the  application 
option  table  with  the  standard  option  table  and  then  calls  the  Xlib  XrmParseCommand  func 
tion.  An  entry  in  the  application  table  with  the  same  name  as  an  entry  in  the  standard  table 
overrides  the  standard  table  entry.  If  an  option  name  is  a  prefix  of  another  option  name,  both 
names  are  kept  in  the  merged  table. 

Structures 

You  make  Xtlnitialize  understand  additional  command-line  options  by  initializing  a 
XrmOptionDescRec  structure  (called  the  options  table)  and  passing  it  as  an  argument  to 
Xtlnitialize. 

typedef   struct    { 

char    *option;  /*   Option   name    in   argv    */ 

char   ^specifier;  /*   Resource  name    (without   application   name) 

XrmOptionKind   argKind;  /*   Which   style   of   option    it    is    */ 

caddr_t   value;  /*   Value   to  provide    if   XrmoptionNoArg    */ 

}    XrmOptionDescRec,    *XrmOptionDescList; 

Each  options  table  entry  consists  of  four  fields: 

•  The  option  to  be  searched  for  on  the  command  line.   As  with  standard  command-line 
options,  Xt  will  automatically  accept  any  unique  abbreviation  of  the  option  specified 
here.  For  example,  the  option  -pixmapWidthlnPixels  will  be  recognized  if  typed  on  the 
command  line  as  -pixmapW.  However,  if  you  wanted  the  option  -pw  to  set  the  same 
resource,  then  you  would  need  another  entry,  since  pw  is  not  the  leading  string  of 
pixmapWidthlnPixels. 

•  The  resource  specification.    This  must  identify  a  widget  resource  or  an  application 
resource,  but  not  provide  a  value.  Since  it  has  the  same  form  as  allowed  in  the  resource 
databases,  it  may  apply  to  a  single  widget  or  to  many  widgets.  If  it  applies  to  no  widgets, 
no  error  message  will  be  issued. 

•  The  argument  style.  This  field  is  one  of  seven  enumerated  constants  describing  how  the 
option  is  to  be  interpreted.  These  constants  are  described  below. 

•  The  value.  This  field  is  the  value  to  be  used  for  the  resource  if  the  argument  style  is 
XrmoptionNoArg.  This  field  is  not  used  otherwise.  Note  that  this  value  must  already 
be  converted  to  the  value  expected  for  the  resource  (often  not  a  string).  You  may  be  able 
to  use  Xt's  type  converter  routines  explicitly  to  convert  this  data  to  the  right  type. 
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The  XrmOptionKind    enum  constants  that  specify  the  various  command-line  argument 
styles  are  as  shown  in  the  table  below: 


Constant 


Meaning 


Xrmopt  ionNoArg 


Xrmopt ion I sArg 


Xrmopt ionStickyArg 


Xrmopt i on SepArg 


Xrmopt ionResArg 


Xrmopt ionSkipArg 
Xrmopt ionSkipNArgs 

Xrmopt ionSkipLine 


Take  the  value  in  the  value  field  of  the  options  table.   For 

example,  this  is  used  for  Boolean  fields,  where  the  option  might 

be  -debug  and  the  default  value  False. 

The  flag  itself  is  the  value  without  any  additional  information. 

For  example,  if  the  option  were  -on,  the  value  would  be  "on." 

This  constant  is  infrequently  used,  because  the  desired  value  such 

as  "on"  is  usually  not  descriptive  enough  when  used  as  an  option 

(-on). 

The  value  is  the  characters  immediately  following  the  option  with 

no  white  space  intervening.   This  is  the  style  of  arguments  for 

some  POSIX  utilities  such  as  uucico  where  -sventure  means  to 

call  system  venture. 

The  next  item  after  the  white  space  after  this  flag  is  the  value. 

For  example,  -fg  blue  would  indicate  that  blue  is  the  value  for  the 

resource  specified  by  -fg. 

The  resource  name  and  its  value  are  the  next  argument  in  argv 

after  the  white  space  after  this  flag.  For  example,  the  flag  might 

be 

-res  basecalc*background: white; 
then  the  resource  name/value  pair  would  be  used  as  is.  This  form 
is  rarely  used  because  it  is  equivalent  to  -xrm,  and  because  the  C 
shell  requires  that  special  characters  such  as  *  be  quoted. 
Ignore  this  option  and  the  next  argument  in  argv. 
Ignore  this  option  and  the  next  XrmOptionDescRec. value 
options 
Ignore  this  option  and  the  rest  of  argv. 


The  options  table  is  passed  to  Xtlnitialize  as  its  third  argument,  and  the  number  of 
options  table  entries  as  the  fourth.  The  Xt  Number  macro  is  a  convenient  way  to  count  the 
number  of  entries  (this  is  only  one  of  many  contexts  in  which  you'll  see  this  macro  used). 

Note  that  you  cannot  override  the  standard  options  by  providing  options  with  the  same  names 
in  your  own  parsing  table.  If  you  try  this,  your  options  with  the  same  names  will  simply  not  be 
set  to  the  values  specified  on  the  command  line.  Instead,  the  standard  options  will  be  set  to 
these  values.  This  was  a  design  decision  in  Xt,  one  of  the  few  cases  where  a  user-interface  pol 
icy  is  enforced.  Uniformity  in  this  basic  area  was  deemed  more  valuable  than  flexibility. 

See  Also 

XtAppInitialize(l),  XtOpenDisplay(l),  X(ToolkitInitialize(l). 
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Name 

XtlnitializeWidgetClass  —  initialize  a  widget  class  without  creating  any  widgets. 

Synopsis 

void  XtlnitializeWidgetClass (object_class) 
WidgetClass  object_class; 

Arguments 

ob  ject_class          Specifies  the  object  class  to  initialize;  may  be  of  class  objectClass  or  any 
subclass  thereof. 

Description 

If  the  specified  widget  class  is  already  initialized,  XtlnitializeWidgetClass  returns 
immediately. 

If  the  class  initialization  procedure  registers  type  converters,  these  type  converters  are  not 
available  until  the  first  object  of  the  class  or  subclass  is  created  or  until  Xtlnitialize 
WidgetClass  is  called.  This  function  is  normally  used  so  that  the  xtVaTypedArg  feature 
of  xtCreateWidget  can  be  used  to  convert  a  resource  value  while  creating  the  first  instance 
of  a  particular  widget  class. 

See  Also 

XtVaCreoteWidget(l),XtVaCreateManagedWidget(l). 
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Name 

XtlnsertEventHandler  —  register  an  event  handler  procedure  that  receives  events  before  or 
after  all  previously  registered  event  handlers. 

Synopsis 

void  XtlnsertEventHandler  (w,  event_mask,  nonmaskable,  proc,  client  data, 

position) 
Widget  w; 

EventMask  event_mask; 
Boolean  nonmaskable; 
XtEventHandler  proc; 
XtPointer  client_data; 
XtListPosition  position; 

Arguments 

w  Specifies  the  widget  for  which  this  event  handler  is  being  registered. 

event_mask       Specifies  the  event  mask  for  which  to  call  this  procedure. 

nonmaskable  Specifies  whether  this  procedure  should  be  called  on  the  nonmaskable  events 
(GraphicsExpose,  NoExpose,  SelectionClear,  Selection- 
Request,  SelectionNotify,  ClientMessage,  and  Mapping- 
Notify). 

proc  Specifies  the  procedure  that  is  to  be  called. 

client_data      Specifies  additional  data  to  be  passed  to  the  client's  event  handler. 

position  Specifies  when  the  event  handler  is  to  be  called  relative  to  other  previously 

registered  handlers. 

Description 

XtlnsertEventHandler  is  identical   to  XtAddEvent Handler  with   the  additional 
posi  tion  argument.  The  two  values  for  posi  ti on  are  described  as  follows: 

Xt  List  Head  The  event  handler  is  registered  so  that  it  will  be  called  before  any  event  han 
dlers  that  were  previously  registered  for  the  same  widget. 

Xt  List  End  The  event  handler  is  registered  to  be  called  after  any  event  handlers  previ 
ously  registered. 

If  the  procedure  is  already  registered  with  the  same  client_data,  the  specified  mask  aug 
ments  the  existing  mask,  and  the  procedure  is  repositioned  in  the  list. 

Structures 

typedef  enum  {XtListHead,  XtListTail}  XtListPosition; 

See  Also 

XtAddEventHandler(\\  XtAddRawEventHandler(\\  XtBuildEventMask(\\  XtlnsertRawEvent- 
Handler(l),  XtRemaveEventHandler(\\  XtRemaveRawEventHandler(V). 
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Name 

XtlnsertRawEventHandler 


register  an  event  handler  procedure  that  receives  events  before  or 
after  all  previously  registered  event  handlers,  without  selecting 
for  the  events. 


Synopsis 

void  XtlnsertRawEventHandler (w,  event_mask,  nonmaskable,  proc,  client_data, 

position) 
Widget  w; 

EventMask  event_mask; 
Boolean  nonmaskable; 
XtEventHandler  proc; 
XtPointer  client_data; 
XtListPosition  position; 


Arguments 

w 

event_mask 

nonmaskable 


proc 

client_data 

position 


Specifies  the  widget  for  which  this  event  handler  is  being  registered. 
Specifies  the  event  mask  for  which  to  call  this  procedure. 

Specifies  a  Boolean  value  that  indicates  whether  this  procedure  should  be 
called  on  the  nonmaskable  events  (NoExpose,  SelectionClear, 
SelectionRequest,  SelectionNotify,  ClientMessage,  and 
MappingNotify). 

Specifies  the  procedure  that  is  to  be  registered. 

Specifies  additional  data  to  be  passed  to  the  client's  event  handler. 

Specifies  when  the  event  handler  is  to  be  called  relative  to  other  previously 
registered  handlers. 


Description 

The  XtlnsertRawEventHandler  function  is  similar  to  XtlnsertEventHandler 
except  that  it  does  not  modify  the  widget's  event  mask  and  never  causes  an  xselect input 
for  the  specified  events.  If  the  procedure  is  already  registered  with  the  same  client_data, 
the  specified  mask  augments  the  existing  mask  and  the  procedure  is  repositioned  in  the  list. 

Structures 

typedef  enum  {XtListHead,  XtListTail}  XtListPosition; 

See  Also 

XtAddEventHondlerd),  XtAddRowEventHandler(l),  XtBuildEventMask(\\  XtlnsertEventHandler -(I), 
XtRemoveEventHandler(l ),  XtRemoveRawEventHandler  ( 1 ). 
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Name 

XtlnstallAccelerators  —  install  a  widget's  accelerators  on  another  widget 

Synopsis 

void  XtlnstallAccelerators (destination,  source) 
Widget  destination; 
Widget  source; 

Arguments 

destination      Specifies  the  widget  in  which  events  specified  in  the  accelerator  table  will  be 
detected. 

source  Specifies  the  widget  whose  actions  will  be  invoked  when  events  occur  in 

destination. 

Description 

It  is  often  convenient  to  be  able  to  bind  events  in  one  widget  to  actions  in  another.  In  particu 
lar,  it  is  often  useful  to  be  able  to  invoke  menu  actions  from  the  keyboard.  The  Intrinsics  pro 
vide  a  facility,  called  accelerators,  that  let  you  accomplish  this.  An  accelerator  table  is  a  trans 
lation  table  that  binds  events  in  the  destination  widget  to  actions  in  the  source  widget.  The 
accelerator  table  can  be  installed  on  one  or  more  destination  widgets.  When  an  event  sequence 
in  destination  would  cause  an  accelerator  action  to  be  invoked,  and  if  the  source  widget  is 
sensitive,  the  actions  are  executed  as  though  triggered  by  the  same  event  sequence  in  source. 
The  event  is  passed  to  the  action  procedure  without  modification.  The  action  procedures  used 
within  accelerators  must  assume  neither  that  the  source  widget  is  realized,  n,or  that  any  fields  of 
the  event  are  in  reference  to  the  source  widget's  window  if  the  widget  is  realized. 

Every  widget  includes  an  XtNaccelerators  resource,  which  is  defined  by  the  Core  widget 
class.  The  actual  value  of  this  resource  can  be  hardcoded  by  the  application  or  set  in  a  resource 
file,  just  like  any  other  resource. 

However,  in  order  for  the  XtNaccelerators  resource  to  actually  be  used,  the  application 
must  call  XtlnstallAccelerators  (or  XtlnstallAllAccelerators).  This  call 
specifies  two  arguments.  The  destination  widget  is  the  widget  whose  translation  table  will 
be  augmented  with  the  accelerator  table  from  the  source  widget  In  other  terms,  you  could 
think  of  the  source  as  "source  of  actions"  and  the  destination  as  "source  of  events."  That  is, 
events  occurring  in  the  destination  widget  will  trigger  actions  in  the  source.  (From  the  event's 
point  of  view,  the  terminology  seems  backwards!  However,  the  terms  source  and  destination  do 
make  sense  in  terms  of  what  is  actually  happening  to  the  translation  table  of  the  destination 
widget) 

For  example,  assume  an  application  whose  top-level  shell  widget  was  named  topLevel,  and 
which  contained  a  Command  widget  instance  named  quit.  Further  assume  that  the  quit 
widget  had  the  following  XtNaccelerators  resource  defined  for  it: 

*quit .accelerators:  \n\ 
<KeyPress>q :  Quit ( ) 
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The  call: 

XtlnstallAccelerators  (topLevel,  quit); 

would  allow  a  "q"  typed  in  the  application's  top-level  window  to  invoke  the  quit  widget's 
Quit  action. 

If  the  display_accelerator  method  in  the  Core  part  of  the  source  widget  class  is  non- 
NULL,  XtlnstallAccelerators  calls  it  with  the  source  widget  and  a  string  representa 
tion  of  the  accelerator  table.  (The  string  representation  of  the  accelerator  table  is  a  canonical 
translation  table  representation,  not  an  exact  replica  of  what  was  registered.)  The  method  is 
invoked  to  inform  the  source  widget  that  its  accelerators  have  been  installed  on  the  destination 
widget  so  it  can  display  them  appropriately. 

Core(3)  describes  the  display_accelerator  method.  Volume  Four,  X  Toolkit  Intrinsics 
Programming  Manual,  has  a  complete  accelerator  programming  example. 

See  Also 

XtInstallAllAccelerators(\) 
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Name 

XtlnstallAIIAccelerators  —  install  all  accelerators  from  a  widget  and  its  descendants  onto  a 

destination  widget 

Synopsis 

void  XtlnstallAIIAccelerators (destination,  source) 
Widget  destination; 
Widget  source; 

Arguments 

destination      Specifies  the  widget  in  which  events  specified  in  the  accelerator  tables  will  be 
detected. 

source  Specifies  the  root  widget  of  the  widget  tree  from  which  the  actions  of  any 

descendant  widget  can  be  invoked  when  events  occur  in  destination. 

Description 

XtlnstallAIIAccelerators  is  a  convenience  function  for  installing  all  accelerators 
from  a  widget  and  all  its  descendants  onto  one  destination  widget  It  recursively  traverses  the 
widget  tree  rooted  at  source  and  installs  the  accelerator  resource  values  of  each  widget  onto 
destination.  A  common  use  is  to  call  XtlnstallAIIAccelerators  and  pass  the 
main  ApplicationShell  widget  as  the  source,  and  the  widget  in  which  accelerator  events  (such 
as  keyboard  events)  are  to  be  detected  as  the  destination.  The  source  and  destination  can  be  the 
same  widget. 

Assuming  the  example  shown  under  xtinstallAccelerators,  the  difference  between: 

XtlnstallAccelerators (topLevel,box) ; 

and 

XtlnstallAIIAccelerators (topLevel,box)  ; 

is  that  in  the  second  case,  the  accelerator  table  for  all  descendants  of  box  will  be  merged  with 
the  translation  table  of  topLevel,  whereas  in  the  first  case,  only  the  accelerator  table  for  box 
itself  will  be  merged  with  the  translation  table  of  topLevel.  In  both  cases,  the  events  speci 
fied  in  the  accelerator  table  or  tables  will  be  detected  in  topLevel. 

Since  topLevel  is  often  completely  hidden  by  the  main  composite  or  constraint  widget  of  an 
application,  how  does  it  get  events?  Because  of  event  propagation,  a  keyboard  or  pointer  event 
that  is  not  selected  in  a  widget  will  propagate  through  that  widget  to  the  widget's  parent  (Only 
user  events  propagate.)  Assuming  that  topLevel  is  an  ApplicationShell  widget,  keyboard  (or 
pointer)  events  that  occur  anywhere  in  the  application  will  trickle  down  to  topLevel  unless 
selected  by  a  child  widget.  This  means  that  by  installing  all  accelerators  on  topLevel  with  a 
source  of  box,  events  that  occur  anywhere  within  topLevel  or  within  any  of  its  descendants 
can  trigger  the  accelerators  and  thereby  invoke  actions  in  box  or  any  of  its  descendants. 

See  Also 

XtlnstallAccelerators 
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J  XtlsApplicationShell 

— Xt  -  Object  Information ' 

Name 

XtlsApplicationShell  —  test  whether  a  widget  is  a  subclass  of  the  ApplicationShell  widget 
class. 

Synopsis 

Boolean  XtlsApplicationShell (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  class  is  to  be  checked;  may  be  of  class  Object  or 

any  subclass  thereof. 

Description 

XtlsApplicationShell  tests  whether  a  widget  is  a  subclass  of  the  ApplicationShell 
widget  class.  This  is  really  just  a  convenience  function  equivalent  to  calling  xtlsSubclass 
with  applicationShellWidgetClass  as  the  object_class  argument.  Xtls 
ApplicationShell  is  defined  as  a  macro  in  <X1  II Intrinsic. h>: 

tdefine  XtlsApplicationShell (widget)  \ 

(_XtIsSubclassOf (widget,  (WidgetClass) applicationShellWidgetClass,  \ 
(WidgetClass)topLevelShellWidgetClass,  (XtEnum) 0x80) ) 

See  Also 

XthSubclass(\\ 
ApplicationShetlQ),  Core(3). 
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XtlsComposite  A 

> Xt  -  Object  Information  — 

Name 

XtlsComposite  —  test  whether  a  widget  is  a  subclass  of  the  Composite  widget  class. 

Synopsis 

Boolean  XtlsComposite (object) 
Widget  object; 

Arguments 

object  Specifies  the  widget  whose  class  is  to  be  tested;  may  be  of  class  Object  or  any 

subclass  thereof. 

Description 

XtlsComposite  tests  whether  a  widget  is  a  subclass  of  the  Composite  widget  class.  This  is 
really  just  a  convenience  function  equivalent  to  calling  xtlsSubclass  with  composite- 
widgetClass  as  the  object_class  argument.  XtlsComposite  is  defined  as  a  macro 
in  <X1  II Intrinsic. h>: 

#define  XtlsComposite (widget )    (_XtCheckSubclassFlag (widget,  (XtEnum) 0x08) ) 

See  Also 

XtlsSubclassd), 
Composite®),  Core(3). 
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J  XtlsConstraint 

— Xt  -  Object  Information ' 

Name 

XtlsConstraint  —  test  whether  a  widget  is  a  subclass  of  the  Constraint  widget  class. 

Synopsis 

Boolean  XtlsConstraint (object) 
Widget  object; 

Arguments 

object  Specifies  the  widget  whose  class  is  to  be  tested;  may  be  of  class  Object  or  any 

subclass  thereof. 

Description 

XtlsConstraint  tests  whether  a  widget  is  a  subclass  of  the  Constraint  widget  class.  This  is 
really  just  a  convenience  function  equivalent  to  calling  xtlsSubclass  with  constraint - 
WidgetClass  as  the  object_class  argument  XtlsConstraint  is  defined  as  a  macro 
in  <X1  II Intrinsic. h>: 

#define   XtlsConstraint (widget)    XtlsSubclass (widget ,     (WidgetClass)    \ 
const raintWidget Class) 

See  Also 

XtlsSubclossd), 
Constraint (3),  Core(3). 
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XtlsManaged  \ 


•Xt  -  Object  Information  — 


Name 

XtlsManaged  —  determine  whether  a  widget  is  managed  by  its  parent. 

Synopsis 

Boolean  XtlsManaged (object) 
Widget  object ; 

Arguments 

object  Specifies  the  object  whose  state  is  to  be  tested;  may  be  of  class  Object  or  any 

subclass  thereof. 

Description 

XtlsManaged  returns  True  if  the  specified  child  widget  is  currently  managed  and  False  if 
the  widget  is  not. 

As  a  macro  for  use  in  widget  code,  XtlsManaged  simply  accesses  the  Core  widget's  man 
aged  field. 

See  Also 

XtManageChildren(\\XtUnmanageChildren(\\ 
Core(3), 
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— Xt  -  Object  Information '  AllSUDjeCt 

Name 

XtlsObject  —  test  whether  a  widget  is  a  subclass  of  the  Object  widget  class. 

Synopsis 

Boolean  XtlsObject (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  class  is  to  be  checked;  may  be  of  object  Class  or 

any  subclass  thereof. 

Description 

XtlsObject  tests  whether  a  widget  is  a  subclass  of  the  Object  widget  class.  This  is  really 
just  a  convenience  function  equivalent  to  calling  xtlsSubclass  with  objectwidget- 
Class  as  the  object_class  argument. 

See  Also 

XtIsSubclass(l), 
Core(3),  Object(3). 
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XtlsOverrideShell  v 

Xt  -  Object  Information  — 

Name 

XtlsOverrideShell  —  test  whether  a  widget  is  a  subclass  of  the  OverrideShell  widget  class. 

Synopsis 

Boolean  XtlsOverrideShell (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  class  is  to  be  checked;  may  be  of  class  Object  or 

any  subclass  thereof. 

Description 

XtlsOverrideShell  tests  whether  a  widget  is  a  subclass  of  the  OverrideShell  widget  class. 
This  is  really  just  a  convenience  function  equivalent  to  calling  Xt  Is  Subclass  with 
overrideShellWidgetClass  as  the  object_class  argument.  XtlsOverride 
Shell  is  defined  as  a  macro  in  <X1  II Intrinsic. h>: 

#define   XtlsOverrideShell (widget)    \ 

(_XtIsSubclassOf (widget,     (WidgetClass) overrideShellWidgetClass,    \ 
(WidgetClass) shellWidgetClass,     (XtEnum) 0x20) ) 

See  Also 

XtlsSubclossd), 
Core(3),  OverrideShell^). 
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_f  XtlsRealized 

— Xt  -  Object  Information ' 

Name 

XtlsRealized  —  determine  whether  a  widget  has  been  realized. 

Synopsis 

Boolean  XtlsRealized (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  state  is  to  be  tested;  may  be  of  class  Object  or  any 

subclass  thereof. 

Description 

XtlsRealized  returns  True  if  the  widget  has  been  realized,  and  False  otherwise.  A 
widget  is  realized  if  it  has  a  nonzero  X  window  ID  in  its  Core  field  window. 

XtlsRealized  is  a  macro  for  use  in  widget  code. 

Some  widget  methods  (for  example,  set_values)  might  wish  to  operate  differently  depend 
ing  on  whether  the  widget  has  been  realized.  In  particular,  no  Xlib  calls  can  refer  to  a  widget's 
window  until  the  widget  is  realized. 

See  Also 

XtIsSubclass(l)t 
Core(3\  RectObjQ). 
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XtlsRectObj  \ 


•Xt  -  Object  Information  — 


Name 

XtlsRectObj  —  test  whether  a  widget  is  a  subclass  of  the  RectObj  widget  class. 

Synopsis 

Boolean  XtlsRectObj (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  class  is  to  be  checked;  may  be  of  class  Object  or 

any  subclass  thereof. 

Description 

XtlsRectObj  tests  whether  a  widget  is  a  subclass  of  the  RectObj  widget  class.  This  is  really 
just  a  convenience  function  equivalent  to  calling  xtlsSubclass  with  rectob jwidget- 
Class  as  the  object_class  argument.  XtlsRectObj  is  defined  as  a  macro  in 
Oil  II Intrinsic. h>: 

#define  XtlsRectObj (object)      (_XtCheckSubclassFlag ( ,  (XtEnum) 0x02) ) 

See  Also 

XtIsSubcloss(\\ 
RectObj(3),  Core(3). 
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_    ,  t       ,  /  XtlsSensitive 

— Xt  -  Object  Information ' 

Name 

XtlsSensitive  —  check  the  current  sensitivity  state  of  a  widget 

Synopsis 

Boolean  XtlsSensitive (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  state  is  to  be  tested;  may  be  of  class  Object  or  any 

subclass  thereof. 

Description 

XtlsSensitive  returns  True  or  False  to  indicate  whether  the  widget  is  sensitive,  (i.e., 
whether  user  input  events  are  being  dispatched  to  its  actions).  If  both  core .  sensitive  and 
core.ancestor_sensitive  are  True,  XtlsSensitive  returns  True;  otherwise,  it 
returns  False. 

A  widget's  sensitivity  is  often  checked  by  its  parent.  For  example  the  parent  may  wish  to 
determine  whether  it  should  should  pass  the  keyboard  focus  to  the  child,  or  it  may  choose  to 
follow  the  lead  of  its  children,  and  make  itself  insensitive. 

See  Also 

XtCallAcceptFocus(l),  XtSetSensitive(l ), 
Core(3). 
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XtlsShell  ~\ V1 

v Xt  -  Object  Information  — 

Name 

XtlsShell  —  test  whether  a  widget  is  a  subclass  of  the  Shell  widget  class. 

Synopsis 

Boolean  XtlsShell (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  class  is  to  be  tested;  may  be  of  class  Object  or  any 

subclass  thereof. 

Description 

XtlsShell  tests  whether  a  widget  is  a  subclass  of  the  Shell  widget  class.  This  is  really  just  a 
convenience  function  equivalent  to  calling  xtlsSubclass  with  shellwidgetClass  as 
the  object_class  argument  XtlsShell  is  defined  as  a  macro  in  <X11  /Intrinsic. h>: 

#define   XtlsShell (widget)         (_XtCheckSubclassFlag (widget,     (XtEnum) 0x20) ) 

See  Also 

XtIsSubcloss(l\ 
Core (3),  Shell(3). 
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^    ,  f      #l   J  XtlsSubclass 

— Xt  -  Object  Information ' 

Name 

XtlsSubclass  —  determine  whether  a  widget  is  a  subclass  of  a  class. 

Synopsis 

Boolean  XtlsSubclass  (object,  obj'ect_class) 
Widget  object; 
WidgetClass  object_class; 

Arguments 

object  Specifies  the  object  instance  whose  class  is  to  be  checked;  may  be  of  class 

Object  or  any  subclass  thereof. 

ob  ject_c  1  ass      Specifies  the  widget  class  to  test  against. 

Description 

If  object  belongs  to  a  derived  class  of  object_class,  then  it  is  a  subclass.  Xt 
lsSubclass  returns  True  if  the  specified  widget  is  a  subclass  of  the  given  class. 

A  widget  is  trivially  a  subclass  of  its  own  widget  class,  or  it  can  be  any  number  of  subclasses 
removed.  XtlsSubclass  starts  with  the  widget _cl ass  field  in  the  Core  class  part  of 
object's  widget  structure  and  follows  the  superclass  pointer  until  it  reaches  the  top  of 
the  class  hierarchy.  If  it  finds  any  match  to  the  class  of  the  specified  widget,  it  returns  True. 

Composite  widgets  that  restrict  the  class  of  widgets  they  will  adopt  as  children  can  use  Xt 
lsSubclass  to  find  out  whether  a  widget  belongs  to  the  desired  widget  class. 

To  test  whether  a  given  widget  is  a  subclass  of  an  Intrinsics-defined  class,  the  Intrinsics  define 
macros  or  functions  equivalent  to  XtlsSubclass  for  each  of  the  built-in  classes.  These  pro 
cedures  are  XtlsObject,  XtlsRectObj,  XtlsWidget,  XtlsComposite,  Xt- 
IsConstraint,  XtlsShell,  XtlsOverrideShell,  XtlsWMShell,  XtlsVendor- 
Shell,  XtlsTransientShell,  XtlsTopLevelShell  and  XtlsApplication- 
Shell. 

All  of  these  macros  and  functions  have  the  same  argument  description: 

Boolean  XtlscJass (object) 
Widget  object; 

object  Specifies  the  object  instance  whose  class  is  to  be  checked.  May  be  of  class 

ob  jectClass  or  any  subclass  thereof. 

These  procedures  may  be  faster  than  calling  XtlsSubclass  directly  for  the  built-in  classes. 
See  Also 

XtCheckSubcloss(\\  XtCloss(l),  XtSuperclass(l), 
Composite®),  Core (3). 
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XtlsTopLevelShell  Yi 

v Xt  -  Object  Information  — 

Name 

XtlsTopLevelShell  —  test  whether  a  widget  is  a  subclass  of  the  TopLevelShell  widget  class. 

Synopsis 

Boolean  XtlsTopLevelShell (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  class  is  to  be  checked;  may  be  of  class  Object  or 

any  subclass  thereof. 

Description 

XtlsTopLevelShell  tests  whether  a  widget  is  a  subclass  of  the  TopLevelShell  widget 
class.  This  is  really  just  a  convenience  function  equivalent  to  calling  Xt  Is  Subclass  with 
topLevelShellwidgetClass  as  the  object_class  argument.  XtlsTopLevel 
Shell  is  defined  as  a  macro  in  <X11  /Intrinsic. h>: 

#define  XtlsTopLevelShell (widget)  (_XtCheckSubclassFlag (widget,  (XtEnum) 0x80) ) 

See  Also 

XtIsSubcloss(l\ 
Core(3\  TopLevelShell^). 
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,      „   J  XtlsTransientShell 

— Xt  -  Object  Information ' 

Name 

XtlsTransientShell  —  test  whether  a  widget  is  a  subclass  of  the  TransientShell  widget  class. 

Synopsis 

Boolean  XtlsTransientShell (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  class  is  to  be  checked;  may  be  of  object  Class  or 

any  subclass  thereof. 

Description 

XtlsTransientShell  tests  whether  a  widget  is  a  subclass  of  the  TransientShell  widget 
class.  This  is  really  just  a  convenience  function  equivalent  to  calling  xtlsSubclass  with 
transientShellWidgetClass  as  the  object_class  argument.  XtlsTransient 
Shell  is  defined  as  a  macro  in  <X1  II Intrinsic. h>: 

#define  XtlsTransientShell (widget)  \ 

(_XtIsSubclassOf (widget,  (WidgetClass) transientShellWidgetClass,  \ 
(WidgetClass)wmShellWidgetClass,  (XtEnum) 0x40) ) 

See  Also 

XtlsSubclass  ( 1 ), 

Core(3),  TransientShellQ). 
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XtlsVendorShell  \ v 

> Xt  -  Object  Information— 

Name 

XtlsVendorShell  —  test  whether  a  widget  is  a  subclass  of  the  VendorShell  widget  class. 

Synopsis 

Boolean  XtlsVendorShell (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  class  is  to  be  checked;  may  be  of  class  Object  or 

any  subclass  thereof. 

Description 

XtlsVendorShell  tests  whether  a  widget  is  a  subclass  of  the  VendorShell  widget  class. 
This  is  really  just  a  convenience  function  equivalent  to  calling  xtlsSubclass  with 
vendorShellWidgetClass  as  the  object_class  argument  XtlsVendorShell  is 
defined  as  a  macro  in  <X1  II Intrinsic. h>: 

#define  XtlsVendorShell (widget)    \ 

(_XtIsSubclassOf (widget,     (WidgetClass) vendorShellWidgetClass,    \ 
(WidgetClass)wmShellWidgetClass,     (XtEnum) 0x40) ) 

See  Also 

XtIsSubcloss(l\ 
Core(3)t  VendorShellQ). 


238  X  Toolkit  Intrinsics  Reference  Manual 


-X.-ObJ.c.  information /  XtlsWidget 

Name 

XtlsWidget  —  test  whether  a  widget  is  a  subclass  of  the  Core  widget  class. 

Synopsis 

Boolean  XtlsWidget (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  class  is  to  be  checked;  may  be  of  class  Object  or 

any  subclass  thereof. 

Description 

XtlsWidget  tests  whether  a  widget  is  a  subclass  of  the  Core  widget  class.  This  is  really  just 
a  convenience  function  equivalent  to  calling  xtlsSubclass  with  coreWidgetClass  as 
the  object_class  argument  XtlsWidget  is  defined  as  a  macro  in  <X1  II Intrinsic. h>: 

tdefine  XtlsWidget (object)  (_XtCheckSubclassFlag (object,  (XtEnum) 0x04) ) 

See  Also 

XtIsSubcloss(\\ 
Core (3),  WidgetQ). 
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XtlsWMShell  \ 

Xt  -  Object  Information— 

Name 

XtlsWMShell  —  test  whether  a  widget  is  a  subclass  of  the  WMShell  widget  class. 

Synopsis 

Boolean  XtlsWMShell (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  class  is  to  be  checked;  may  be  of  class  Object  or 

any  subclass  thereof. 

Description 

XtlsWMShell  tests  whether  a  widget  is  a  subclass  of  the  WMShell  widget  class.  This  is 
really  just  a  convenience  function  equivalent  to  calling  XtlsSubclass  with  WMShell- 
WidgetClass  as  the  object_class  argument.  XtlsWMShell  is  defined  as  a  macro  in 
<X1  II Intrinsic. h>: 

#define   XtlsWMShell (widget)       (_XtCheckSubclassFlag (widget,     (XtEnum) 0x40) ) 

See  Also 

XtIsSubcloss(l\ 
Core(3),  WMShell(3). 
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„  .      .u        )  XtKeysymToKeycodeList 

— Xt-  Keyboard  Handling '  '     * 

Name 

XtKeysymToKeycodeList  —  return  the  list  of  keycodes  that  map  to  a  particular  keysym  in  the 

keyboard  mapping  table  maintained  by  the  Intrinsics. 

Synopsis 

void  XtKeysymToKeycodeList (display,  keysym,  keycodes_return,  key- 

count_return) 
Display  * display; 
KeySym  keysym; 
KeyCode  **£eycodes_retu.m; 
Cardinal  *keycount_return; 

Arguments 

display  Specifies  the  display  whose  table  is  required. 

keysym  Specifies  the  keysym  for  which  to  search. 

keycodes_return    Returns  a  list  of  keycodes  that  have  keysyms  associated  with  them  or 
NULL  if  keycount_return  is  0. 

keycount_return    Returns  the  number  of  keycodes  in  the  keycodes  list. 

Description 

The  XtKeysymToKeycodeList  procedure  returns  all  the  keycodes  that  have  the  requested 
keysym  in  their  entry  for  the  keyboard  mapping  table  associated  with  display.  For  each 
entry  in  the  table,  the  first  four  keysyms  (groups  1  and  2)  are  interpreted  as  specified  by  the  X 
Protocol  specification.  If  no  keycodes  map  to  the  specified  keysym,  keycount_return  is  0 
and  *£eycodes_retur/j  is  NULL. 

The  caller  should  free  the  storage  pointed  to  by  keycodes_return  using  xtFree  when  it 
is  no  longer  useful.  If  the  caller  needs  to  examine  the  keycode-to-keysym  table  for  a  particular 
keycode,  it  should  call  XtGetKeysymTable. 

See  Also 

XtConvertCose(\\  XtGetKeysymToble(\\  XtRegisterCoseConverter(l\  XtSetKeyTranslator(l\  Xt- 
TranslateKeycode(l). 
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XtLastTimestampProcessed         \  -  xt  _  Evem  HandMng_ 


Name 

XtLastTimestampProcessed  —  retrieve  the  timestamp  from  the  most  recent  event  handled  by 

XtDispatchEvent  that  contains  a  timestamp. 

Synopsis 

Time  XtLastTimestampProcessed  (  display) 
Display  *  display; 

Arguments 

display  Specifies  an  open  display  connection. 

Description 

If  no  KeyPress,  KeyRelease,  ButtonPress,  ButtonRelease,  MotionNotify, 
EnterNotify,  LeaveNotify,  PropertyNotify  or  SelectionClear  event  has  yet 
been  passed  to  XtDispatchEvent  for  the  specified  display,  XtLastTimestamp 
Processed  returns  zero. 

See  Also 

XtDispotchEvent(l),  XtGetSelectionVolue(\),  XtOwnSelection(l). 
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f  XtMainLoop 

— Xt  -  Event  Handling ' 

Name 

XtMainLoop  —  continuously  process  events. 

Synopsis 

void  XtMainLoop () 

Description 

XtMainLoop  has  been  superseded  by  xtAppMainLoop.  XtMainLoop  obtains  the  default 
application  context  and  reads  the  next  incoming  X  event  by  calling  xtAppNext Event.  It 
then  dispatches  the  appropriate  registered  procedure  with  xtDispatchEvent.  This  consti 
tutes  the  main  loop  of  Toolkit  applications,  and,  as  such,  it  does  not  return.  Applications  are 
expected  to  exit  in  response  to  some  user  action.  (xtAppAddWorkProc  provides  a  way  of 
using  an  application's  idle  time.)  There  is  nothing  special  about  XtMainLoop;  it  is  simply  an 
infinite  loop  that  calls  XtAppNextEvent  and  then  XtDispatchEvent. 

An  application  can  provide  its  own  version  of  this  loop.  For  example,  it  might  test  an  applica 
tion-dependent  global  flag  or  other  termination  condition  before  looping  back  and  calling  Xt 
AppNextEvent.  Instead  of  exiting  on  a  particular  event  (say  a  button  press),  it  might  exit  if 
the  number  of  top-level  widgets  drops  to  zero. 

See  Also 

XtAppAddWorkProc(\\  XtAppMainLoop  (\\  XtAppNextEvent(\\  XtDispatchEvent^. 


X  Toolkit  Intrinsics  Reference  Manual  243 


XtMakeGeometryRequest 

v Xt  -  Geometry  Management- 
Name 

XtMakeGeometryRequest  —  request  parent  to  change  child's  geometry. 

Synopsis 

XtGeometryResult  XtMakeGeometryRequest (w,  request,  reply_return) 
Widget  w, 

XtWidgetGeometry  *request; 
XtWidgetGeometry  *reply_return; 

Arguments 

w  Specifies  the  child  widget  that  is  making  the  request 

request        Specifies  the  desired  widget  geometry  (size,  position,  border  width,  and  stacking 
order). 

rep ly_re turn 

Returns  the  allowed  widget  size  or  may  be  NULL  if  the  requesting  widget  is  not 
interested  in  handling  xtGeometryAlmost. 

Description 

Child  widgets  are  not  allowed  to  change  their  own  size  or  position.  Instead,  a  child  uses  Xt 
MakeGeometryRequest  to  ask  its  parent  to  change  its  geometry.  XtMakeGeometry 
Request  returns  Xt  Geometry  Yes,  XtGeometryNo,  or  XtGeometryAlmost.  (See 
below.) 

XtMakeGeometryRequest  performs  the  following  tasks: 

•  If  the  widget  is  unmanaged  or  the  widget's  parent  is  not  realized,  it  makes  the  changes  to 
the  widget's  preferred  geometry  and  returns  Xt  Geometry  Yes. 

•  If  the   parent   is   not  a   subclass   of  compositeWidgetClass   or  the   parent's 
geometry_manager  method  (the  function  pointed  to  by  the  geometry_manager 
field  in  the  widget  class  record)  is  NULL,  it  issues  an  error. 

•  If  the  widget's  being_dest  royed  field  is  True,  it  returns  XtGeometryNo. 

•  If  the  widget  x,  y,  width,  height,  and  border_width  fields  are  already  equal  to  the 
requested    values,    it  returns   Xt  Geometry  Yes;    otherwise,    it   calls    the   parent's 
geometry_manager  method  with  the  given  parameters. 

•  If  the  parent's  geometry  manager  returns  XtGeometryYes,  if  xtCWQueryOnly  is  not 
set  in  request_mode  (see  Structures  below  for  details),  and  if  the  widget  is  realized, 
then  XtMakeGeometryRequest  calls  the  Xlib  XConfigureWindow  function  to 
adjust  the  widget's  window  (setting  its  size,  location,  and  stacking  order  as  appropriate). 

•  If  the  geometry  manager  returns  XtGeometryDone,  the  change  has  been  approved  and 
actually  has  been  done.  In  this  case,  XtMakeGeometryRequest  does  no  configuring 
and   returns   XtGeometryYes.    XtMakeGeometryRequest   never  returns   xt- 
Geomet  ryDone. 

Otherwise,  XtMakeGeometryRequest  returns  the  resulting  value  from  the  parent's 
geometry  manager. 
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Xt  -  Geometry  Management  (continued)  XtMakeGeometry Request 

Children  of  primitive  widgets  are  always  unmanaged;  thus,  xtMakeGeometryRequest 
always  returns  xtGeometryYes  when  called  by  a  child  of  a  primitive  widget. 

Structures 

The  return  codes  from  geometry  managers  are: 

typedef   enum  _XtGeometryResult    { 

XtGeometryYes,         /*    Request    accepted   */ 

XtGeometryNo,  /*    Request   denied    */ 

XtGeometryAlmost, /*    Request   denied  but   willing   to   take    reply    */ 

XtGeometryDone        /*    Request   accepted   and   done    */ 
}    XtGeometryResult; 

The  Xtwidget Geometry  structure  is  similar  to  but  not  identical  to  the  corresponding  Xlib 
structure: 

typedef   unsigned   long   XtGeometryMask; 

typedef   struct    { 

XtGeometryMask   request_mode; 

Position   x,    y; 

Dimension  width,  height; 

Dimension  border_width; 

Widget  sibling; 

int  stack_mode; 
}  XtWidgetGeometry; 

The  request_mode  definitions  are  from  <Xll/X.h>: 

#define  CWX  (1«0) 

#define  CWY  (1«1) 

#define  CWWidth  (1«2) 

#define  CWHeight  (1«3) 

#define  CWBorderWidth  (1«4) 

tdefine  CWSibling  (1«5) 

#define  CWStackMode  (1«6) 

The  Xt  Intrinsics  also  support  the  following  value: 

tdefine  XtCWQueryOnly    (1«7) 

XtCWQueryOnly  indicates  that  the  corresponding  geometry  request  is  only  a  query  as  to  what 
would  happen  if  this  geometry  request  were  made  and  that  no  widgets  should  actually  be 
changed. 

XtMakeGeometryRequest,  like  the  Xlib  XConfigureWindow  function,  uses 
request_mode  to  determine  which  fields  in  the  XtWidgetGeometry  structure  you  want 
to  specify. 
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#define 

Above 

#define 

Below 

#def  ine 

Toplf 

#define 

Bottomlf 

#define 

Opposite 

XtMakeGeometry Request  (continued)  Xt  -  Geometry  Management 

The  stackjmode  definitions  are  from  <Xll/X.h>: 

o 

i 

2 

3 

4 

The  Intrinsics  also  support  the  following  value: 

#define        XtSMDontChange        5 

XtSMDont Change  indicates  that  the  widget  wants  its  current  stacking  order  preserved.  For 
precise  definitions  of  Above,  Below,  Toplf ,  Bottomlf ,  and  Opposite,  see  the  reference 
page  for  XConf  igureWindow  in  Volume  Two,  Xlib  Reference  Manual. 

See  Also 

XtMakeResizeRequest  (1 ) 
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.   „  t J  XtMakeResizeRequest 

— Xt  -  Geometry  Management ' 

Name 

XtMakeResizeRequest  —  request  parent  to  change  child's  size. 

Synopsis 

XtGeometryResult  XtMakeResizeRequest ( w,  width,  height,  width_return, 

height_return) 
Widget  w; 

Dimension  width,  height; 
Dimension  *width_return,  *height_return 

Arguments 

vi  Specifies  the  child  widget  making  the  request. 

width,  height         Specify  the  desired  widget  width  and  height. 

width_return,  height__return 

Return  the  allowed  widget  width  and  height. 
Description 

XtMakeResizeRequest  is  a  simplified  version  of XtMakeGeometryRequest.  A  child 
uses  XtMakeResizeRequest  to  ask  its  parent  to  change  its  size. 

XtMakeResizeRequest  creates  an  XtWidgetGeometry  structure  and  specifies  that 
width  and  height  should  change.  The  geometry  manager  is  free  to  modify  any  of  the  other 
window  attributes  (position  or  stacking  order)  to  satisfy  the  resize  request. 

If  the  return  value  is  XtGeometryAlmost,  width_return  and  height_return  contain 
a  compromise  width  and  height.  If  these  are  acceptable,  the  widget  should  immediately  make 
another  XtMakeResizeRequest  and  request  that  the  compromise  width  and  height  be 
applied.  If  the  widget  is  not  interested  in  XtGeometryAlmost  replies,  it  can  pass  NULL  for 
width_return  and  height_return. 

For  more  information,  see  Chapter  11,  Geometry  Management,  in  Volume  Four,  X  Toolkit 
Intrinsics  Programming  Manual. 

Structures 

The  return  codes  from  geometry  managers  are: 

typedef  enum  _XtGeometryResult  { 

XtGeometryYes,    /*  Request  accepted  */ 

XtGeometryNo,     /*  Request  denied  */ 

XtGeometryAlmost,/*  Request  denied  but  willing  to  take  reply  */ 

XtGeometryDone   /*  Request  accepted  and  done  */ 
}  XtGeometryResult; 

See  Also 

XtMakeGeometryRequest(l ) 
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XtMalloc 

Xt  -  Memory  Allocation  — 

Name 

XtMalloc  —  allocate  storage. 

Synopsis 

char  *XtMalloc (size) ; 
unsigned  int  size; 

Arguments 

si  ze  Specifies  the  number  of  bytes  desired. 

Description 

XtMalloc  returns  a  pointer  to  a  block  of  storage  of  at  least  the  specified  si  ze  bytes.  If  there 
is  insufficient  memory  to  allocate  the  new  block,  XtMalloc  terminates  by  calling  xtError- 
Msg. 

If  a  widget  is  passed  a  pointer  to  resource  data,  it  is  expected  to  recopy  the  actual  data  into 
space  of  its  own,  so  the  application  can  do  whatever  it  wants  with  its  own  data.  The  best  way  to 
preserve  data  is  to  allocate  memory  with  XtMalloc  and  copy  the  data  there. 

XtMalloc  makes  no  guarantee  about  the  contents  of  the  memory  when  it  is  allocated. 

Memory  allocated  with  XtMalloc  must  be  deallocated  with  xtFree.  The  function  Xt 
Malloc  is  implemented  by  the  Toolkit  independently  of  the  particular  environment,  so  pro 
grams  ported  to  a  system  not  supporting  malloc  will  still  work. 

XtNew  and  XtNewString  provide  slightly  higher-level  approaches  to  memory  allocation. 
See  Also 

XtCalloc(\\  XtErrorMsg(l\  XtFree(\\  XtNew(l\  XtNewString (1),  XtRealloc(l). 
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-x,  -  wwge,  uecyc* /  XtManageChild 

Name 

XtManageChild  —  add  a  widget  to  its  parent's  list  of  managed  children. 

Synopsis 

void  XtManageChild ( w) 
Widget  w; 

Arguments 

w  Specifies  the  child  widget  to  be  managed. 

Description 

XtManageChild  brings  a  child  widget  created  with  xtCreateWidget  under  the  geometry 
management  of  its  parent.  A  widget  cannot  be  made  visible  until  it  is  managed. 

XtManageChild  constructs  a  WidgetList  of  length  one  and  calls  XtManageChildren. 
Calling  XtManageChild  or  XtManageChildren  can  be  bypassed  if  widgets  are  created 
with  XtCreateManagedWidget. 

Note  that  XtManageChild,  XtManageChildren,  XtUnmanageChild,  and  Xt- 
UnmanageChildren  are  low-level  routines  that  are  used  by  generic  composite  widget  build 
ing  routines.  In  addition,  composite  widgets  can  provide  widget-specific,  high-level  conve 
nience  procedures  to  let  applications  create  and  manage  children  more  easily. 

See  Also 

XtCreateManagedWidget(Y),  XtIsManaged(\\  XtManageChildren(\),  XtSetMappedWhenManaged(l), 
XtUnmanageChild(\ ),  XtUnmanageChlldren(\ ). 
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XtManageChildren  \ 

> Xt  -  Widget  Lifecycle  — 

Name 

XtManageChildren  —  add  widgets  to  their  parent's  list  of  managed  children. 

Synopsis 

void  XtManageChildren (children,  num_children) 
WidgetList  children; 
Cardinal  num_children; 

Arguments 

chi  l  dren  Specifies  an  array  of  child  widgets. 

n  um_chi  l  dren         Specifies  the  number  of  children  in  the  array. 
Description 

XtManageChildren  brings  a  list  of  widgets  created  with  XtCreateWidget  under  the 
geometry  management  of  their  parent  A  widget  cannot  be  made  visible  until  it  is  managed.  (A 
widget  can  be  created  and  managed  at  the  same  time  by  calling  the  convenience  function  xt  - 

CreateManagedWidget.) 

XtManageChildren  performs  the  following: 

Issues  an  error  if  the  children  do  not  all  have  the  same  parent  or  if  the  parent  is  not  a  sub 
class  of  compositeWidgetClass.  It  returns  immediately  if  the  common  parent  is 
being  destroyed. 

•  Marks  each  child  viewable  that  is  not  already  under  management  and  not  being  des 
troyed. 

•  For  each  viewable  child,  if  the  parent  is  realized,  XtManageChildren: 

Calls  the  parent's  change_managed  method. 
Calls  XtRealizeWidget  if  the  child  is  unrealized. 
Maps  child  if  map_when_managed  is  True. 

Managing  children  is  independent  of  their  ordering  and  their  creation  and  deletion.  The  parent 
should  lay  out  only  children  whose  managed  field  is  True  and  ignore  all  others.  Note  that 
some  composite  widgets,  especially  fixed  boxes,  call  xtManageChild  from  their 
insert_child  method. 

If  the  parent  widget  is  realized,  its  change_managed  method  is  called  to  notify  it  that  its  set 
of  managed  children  has  changed.  The  parent  can  reposition  and  resize  any  of  its  children.  It 
moves  each  child  as  needed  by  calling  xtMoveWidget,  which  first  updates  the  x  and  y  fields 
and  then  calls  the  Xlib  XMoveWindow  function  if  the  widget  is  realized. 

If  the  composite  widget  wishes  to  change  the  size  or  border  width  of  any  of  its  children,  it  calls 
xtResizeWidget,  which  first  updates  the  Core  fields  and  then  calls  the  Xlib 
XConf  igureWindow  function  if  the  widget  is  realized. 

Calling  XtManageChild  or  XtManageChildren  explicitly  can  be  bypassed  if  widgets  are 
created  with  the  convenience  function  xtCreateManagedWidget.  Note  that  XtManage 
Child,  XtManageChildren,  XtUnmanageChild,  and  XtUnmanageChildren  are 
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xt  -  widget  Lifecycie  (continued)  XtManageChildren 

low-level  routines  that  are  used  by  generic  composite  widget  building  routines.  In  addition, 
composite  widgets  can  provide  widget-specific,  high-level  convenience  procedures  to  let  appli 
cations  create  and  manage  children  more  easily. 

Structures 

typedef  Widget  * Widget List; 

See  Also 

XtCreateManagedWidget(l),  XtIsManaged(l\  XtManageChild(l),  XtMoveWidget(l),  XtRealize- 
Widget(l\  XtResizeWidget(l),  XtSetMappedWhenManaged(l),  XtUnmanageChild(l),  XtUnmanage- 
ChUdren(\\ 
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XtMapWidget  \ 

v Xt  -  Widget  Lifecycle— 

Name 

XtMapWidget  —  map  a  widget  to  its  display. 

Synopsis 

XtMapWidget  (w) 
Widget  w; 

Arguments 

w  Specifies  the  widget  to  be  mapped. 

Description 

XtMapWidget  maps  a  widget's  window  to  its  display,  causing  it  to  become  visible.  A  widget 
must  be  realized  before  it  can  be  mapped. 

If  a  widget's  Core  map_when_managed  field  is  set  to  True,  the  widget  is  automatically 
mapped  when  it  is  managed.  This  is  the  case  for  most  widgets.  Widgets  that  are  not  must  be 
mapped  explicitly  with  XtMapWidget.  The  map_when_managed  field  can  also  be  set 
through  a  call  to  XtSetMappedWhenManaged. 

See  Also 

XtSetMappedWhenManaged(\\  XtUnmapWidget(\\ 
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/  XtMenuPopdown 

—  Xt-PopUps * 

Name 

XtMenuPopdown  —  built-in  action  for  popping  down  a  widget 

Synopsis 

void  XtMenuPopdown (she ll_name) 
String  shell_name; 

Arguments 

she i  l_name       Specifies  the  name  of  the  widget  shell  to  pop  down. 

Description 

Pop-ups  can  be  popped  down  through  several  mechanisms: 

•  A  call  to  XtPopdown 

•  The  supplied  callback  procedure  XtCallbackPopdown 

•  The  standard  translation  action  XtMenuPopdown 

To  pop  down  a  spring-loaded  menu  when  a  pointer  button  is  released  or  when  the  pointer  is 
moved  into  some  window,  use  XtMenuPopdown  (or  its  synonym,  MenuPopdown). 

XtMenuPopdown  is  known  to  the  Translation  Manager,  which  must  perform  special  actions 
for  spring-loaded  pop  ups.  All  that  is  necessary  is  to  map  XtMenuPopdown  to  some  event  or 
event  sequence  using  a  translation  specification  in  a  resource  file.  Calls  to  XtMenuPopdown 
in  a  translation  specification  are  mapped  into  calls  to  a  nonexported  action  procedure. 

If  a  shell  name  is  not  given  as  an  argument,  XtMenuPopdown  calls  XtPopdown  with  the 
widget  for  which  the  translation  is  specified.  If  a  shell_name  is  specified  in  the  translation 
table,  XtMenuPopdown  tries  to  find  the  shell  by  looking  up  the  widget  tree  starting  at  the  par 
ent  of  the  widget  in  which  it  is  invoked.  If  it  finds  a  shell  with  the  specified  name  in  the  pop-up 
children  of  that  parent,  it  pops  down  the  shell;  otherwise,  it  moves  up  the  parent  chain  as 
needed.  If  XtMenuPopdown  gets  to  the  application  top-level  shell  widget  and  cannot  find  a 
matching  shell,  it  generates  a  warning  and  returns  immediately. 

See  Also 

XtCollbackPopdown(\\  XtMenuPopup(\},  XtPopDown(\\  XtPopup(l),  XtPopupSpringLoaded(l). 


X  Toolkit  Intrinsics  Reference  Manual  253 


XtMenuPopup  \ 

v Xt  -  Pop  Ups— 

Name 

XtMenuPopup  —  built-in  action  for  popping  up  a  widget 

Synopsis 

void  XtMenuPopup (she ll_name) 
String  shell_name; 

Arguments 

sheil_name       Specifies  the  name  of  the  widget  shell  to  pop  up. 

Description 

XtMenuPopup  (and  its  synonym  MenuPopup)  is  a  built-in  action  that  pops  up  a  widget.  Xt 
MenuPopup  must  be  specified  in  a  translation  for  ButtonPress,  KeyPress,  or  an 
EnterWindow  event. 

XtMenuPopup  is  known  to  the  Translation  Manager,  which  registers  the  corresponding 
built-in  action  procedure  xtMenuPopupAction.  This  action  procedure  uses  an  xt- 
RegisterGrabAction  routine  with: 

•  owner_events  set  to  True. 

•  event_mask  set  to  ButtonPressMask  |  ButtonReleaseMask. 

•  pointer_mode  and  £eyjboard_/node  set  to  GrabModeAsync. 

If  XtMenuPopup  is  invoked  on  ButtonPress,  it  calls  XtPopupSpringLoaded  on  the 
specified  shell  widget  If  XtMenuPopup  is  invoked  on  KeyPress  or  EnterWindow,  it 
calls  XtPopup  on  the  specified  shell  widget  with  grab_kind  set  to  xtGrab- 
Nonexclusive.  Otherwise,  the  translation  manager  generates  a  warning  message  and 
ignores  the  action. 

When  the  widget  is  popped  up,  XtMenuPopup  performs  the  following  actions: 

•  Calls  XtCheckSubclass  to  ensure  popup_shell  is  a  subclass  of  Snell. 

•  Returns  if  the  shell's  popped_up  field  is  already  T  rue. 

•  Calls  the  callback  procedures  on  the  shell's  popup_callback  list. 

•  Sets    the    shell    popped_up    field    to    True    and    the    shell    grab_kind    and 
spring_l oaded  fields  appropriately. 

•  If  the  shell's  create_popup_chi Id  field  is  non-NULL,  it  is  called  with  popup_shell 
as  the  parameter. 

•  Calls: 

XtAddGrab (popup_shellf     (grab_kind  ==   XtGrabExclusive) , 
spring_loaded) 

•  Calls  XtRealizeWidget  with  popup_shell  specified. 

•  Calls  XMapRaised  with  popup_shell  specified. 
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Xt-PopUps  (continued)  XtMenuPopUp 

(Note  that  these  steps  are  the  same  as  those  for  xtPopup.)  xtMenuPopup  tries  to  find  the 
shell  by  searching  the  widget  tree  starting  at  the  parent  of  the  widget  in  which  it  is  invoked.  If 
it  finds  a  shell  with  the  specified  name  in  the  pop-up  children  of  that  parent,  it  pops  up  the  shell 
with  the  appropriate  parameters.  Otherwise,  it  moves  up  the  parent  chain  as  needed.  If  xt  - 
MenuPopup  gets  to  the  application  widget  and  cannot  find  a  matching  shell,  it  generates  a 
warning  and  returns  immediately. 

See  Also 

XtMenuPopdown(l),  XtPopDown(\)t  XtPopup(l),  XtPopupSpringLoaded(\). 
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X  t  Merge  A  rg  Lists  A 

v Xt-  Memory  Allocation  — 

Name 

XtMergeArgLists  —  merge  two  ArgList  structures. 

Synopsis 

ArgList  XtMergeArgLists (argsl,  num_argsl,  args2,  num_args2) 
ArgList  argsl; 
Cardinal  num_argsl; 
ArgList  args2; 
Cardinal  num_args2; 

Arguments 

argsl  Specifies  the  first  ArgList. 

num_argsl  Specifies  the  number  of  arguments  in  the  first  argument  list. 

args2  Specifies  the  second  ArgList. 

num_args2  Specifies  the  number  of  arguments  in  the  second  argument  list. 

Description 

XtMergeArgLists  allocates  a  new  ArgList  large  enough  to  hold  argsl  and  args2  and 
copies  both  into  it  It  does  not  check  for  duplicate  entries. 

When  the  new  ArgList  is  no  longer  needed,  the  application  program  can  return  it  to  the  free 
pool  with  XtFree. 

Structures 

Arg  is  defined  as  follows  in  <X1  II Intrinsic. h>: 

typedef  struct  { 

String  name; 

XtArgVal  value; 
}  Arg,  * ArgList; 

See  Also 

XtFree(\),  XtSetArg(l). 
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f  XtMoveWidget 

— -Xt  -  Geometry  Management ' 

Name 

XtMoveWidget  —  move  a  widget  on  the  display. 

Synopsis 

void  XtMoveWidget (w,  x,  y) 
Widget  w; 
Position  x; 
Position  y; 

Arguments 

w  Specifies  the  widget  to  be  moved. 

x,  y  Specify  the  new  widget  x  and  y  coordinates. 

Description 

XtMoveWidget  returns  immediately  if  the  specified  geometry  fields  for  the  widget  are  the 
same  as  the  old  values.  Otherwise,  XtMoveWidget  writes  the  new  x  and  y  values  into  the 
widget  and,  if  the  widget  is  realized,  issues  an  Xlib  XMoveWindow  call  on  the  widget's  win 
dow. 

The  XtConf  igureWidget  widget  resizes  and  moves  a  widget.  A  parent  widget  can  use 
XtMoveWidget  or  XtConf  igureWidget  to  rearrange  its  children  on  the  display.  A  child 
widget  must  use  XtMakeGeometryRequest  and  XtMakeResizeRequest  to  ask  its  par 
ent  to  move  or  resize  it;  it  cannot  move  or  resize  itself. 

See  Also 

XtConfigureWidget(l),  XtMakeGeometryRequest(\\  XtMakeResizeRequest(\\  X(TranslateCoords(\). 
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XtName  \ 

^- Xt  -  Object  Information — 

Name 

XtName  —  return  a  pointer  to  the  instance  name  of  the  specified  object. 

Synopsis 

String  XtName (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  name  is  desired;  may  be  of  class  Object  or  any 

subclass  thereof. 

Description 

XtName  returns  a  pointer  to  the  instance  name  of  the  specified  object.  The  storage  is  owned  by 
the  Intrinsics  and  must  not  be  modified.  The  name  is  not  qualified  by  the  names  of  any  of  the 
object's  ancestors. 

See  Also 

XtNameToWidgetd) 
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v#  OK,  tlf      #l   XtNameToWidget 

— Xt  -  Object  Information * 

Name 

XtNameToWidget  —  translate  a  widget  name  to  a  widget  instance. 

Synopsis 

Widget  XtNameToWidget (reference,  name); 
Widget  reference; 
String  names; 

Arguments 

reference         Specifies  the  widget  from  which  the  search  is  to  start.   May  be  of  class 
Object  or  any  subclass. 

names  Specifies  the  partially  qualified  name  of  the  desired  widget. 

Description 

XtNameToWidget  searches  for  a  descendant  of  the  reference  widget  whose  name 
matches  the  specified  names.  The  names  argument  specifies  a  simple  object  name  or  a  series 
of  simple  object  name  components  separated  by  periods  or  asterisks.  XtNameToWidget 
returns  the  descendant  with  the  shortest  name  that  matches  the  specification  according  to  the 
following  rules  (where  child  is  either  a  pop-up  child  or  a  normal  child  if  the  widget  is  a  sub 
class  of  Composite): 

•  Enumerate  the  object  subtree  rooted  at  reference  widget  in  breadth-first  order,  quali 
fying  the  name  of  each  object  with  the  names  of  all  its  ancestors  up  to  but  not  including 
reference.  The  ordering  between  children  of  a  common  parent  is  not  defined. 

•  Return  the  first  object  in  the  enumeration  that  matches  the  specified  names,  where  each 
component  of  names  matches  exactly  the  corresponding  component  of  the  qualified 
object  name  and  an  asterisk  matches  any  series  of  components,  including  none. 

•  If  no  match  is  found,  return  NULL. 

Since  breadth-first  traversal  is  specified,  the  descendant  with  the  shortest  matching  name  (i.e., 
the  fewest  number  of  components),  if  any,  will  always  be  returned.  However,  since  the  order  of 
enumeration  of  children  is  undefined  and  since  the  Intrinsics  do  not  require  that  all  children  of  a 
widget  have  unique  names,  XtNameToWidget  may  return  any  child  that  matches  if  there  are 
multiple  objects  in  the  subtree  with  the  same  name(s).  Consecutive  separators  (periods  or 
asterisks)  that  contain  at  least  one  asterisk  are  treated  as  a  single  asterisk.  Consecutive  periods 
are  treated  as  a  single  period. 

Chapter  12,  Menus,  Gadgets,  and  Cascaded  Pop  Ups,  in  Volume  Four,  X  Toolkit  Intrinsics 
Programming  Manual,  presents  a  discussion  and  an  example  of  XtNameToWidget. 

See  Also 

XtCreateManagedWidget(l),  XtCreatePopupShell(l),  XtCreateWidget(l). 
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XtNew  \ 

v Xt-  Memory  Allocation  — 

Name 

XtNew  —  allocate  storage  for  one  instance  of  a  data  type. 

Synopsis 

type   *XtNew(type) 
type; 

Arguments 

type  Specifies  a  previously  declared  data  type. 

Description 

XtNew  is  used  to  allocate  storage  for  one  instance  of  a  data  type.  It  returns  a  pointer  to  the 
allocated  storage.  For  example,  XtNew  (xtCallbackList)  allocates  storage  for  one  call 
back  list  structure. 

If  there  is  insufficient  memory  to  allocate  the  new  block,  xtErrorMsg  terminates  execution. 
XtNew  is  a  convenience  macro  that  calls  xtMalloc  with  the  following  arguments  specified: 

(    (type    *)    XtMalloc (    (unsigned)    sizeof(type)    )    ) 
To  copy  an  instance  of  a  string,  use  XtNewString. 

See  Also 

XtMalloc(l),  XtNewString  (I). 


260  X  Toolkit  Intrinsics  Reference  Manual 


J  XtNewString 

— Xt  -  Memory  Allocation ' 

Name 

XtNewString  —  copy  an  instance  of  a  string. 

Synopsis 

String  XtNewString (string) 
String  string; 

Arguments 

string  Specifies  a  NULL-terminated  string. 

Description 

XtNewString  is  used  to  copy  an  instance  of  a  string.  It  returns  a  pointer  to  the  allocated  stor 
age.  If  there  is  insufficient  memory  to  allocate  the  new  block,  XtNewString  calls  xt- 
ErrorMsg.  For  example,  xtNew  (xtCallbackList)  allocates  storage  for  one  callback 
list  structure.  XtNewString  is  a  macro  that  allocates  storage  for  a  string,  copies  the  string 
into  the  new  storage,  and  returns  the  pointer.  For  example,  a  string  can  be  copied  into  new  stor 
age  using  the  following: 

static   String  buf[]    =   "How  do  you   do?"; 
String  p; 

p   =   XtNewString (buf ); 

After  this  sequence,  p  points  to  a  separate  string  that  contains  "How  do  you  do?"  Then  buf 
can  be  changed  without  affecting  p. 

XtNewString  is  a  convenience  macro  that  calls  xtMalloc  with  the  following  arguments 
specified: 

(strcpy (XtMalloc ( (unsigned)  strlen(str)  +  1),  str) ) 

See  Also 

XtMalloc(\\  XtNew(l),  XtFree(\\ 
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XtNextEvent 

Xt-  Event  Handling  — 

Name 

XtNextEvent  —  return  next  event  from  input  queue. 

Synopsis 

void  XtNextEvent (event_return) 
XEvent  *event_return; 

Arguments 

event_return         Returns  the  event  information  from  the  dequeued  event  structure. 

Description 

XtNextEvent  has  been  superseded  by  XtAppNext Event.   XtNextEvent  obtains  the 
default  application  context,  and  invokes  XtAppNext  Event. 

See  Also 

XtAppNextEvenl(\ ) 
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/  XtNumber 

— Xt  -  Argument  Lists * 

Name 

XtNumber  —  determine  the  number  of  elements  in  a  fixed-size  array. 

Synopsis 

Cardinal  XtNumber (array) 
array; 

Arguments 

array  Specifies  a  fixed-size  array. 

Description 

XtNumber  returns  the  number  of  elements  in  the  specified  argument  list,  resource  list,  or  other 
fixed-size  array.  It  works  only  for  objects  whose  total  size  is  known  at  compile  time. 

It  is  a  macro  defined  in  <Xll/Xt  Intrinsic.h>  as: 

#define   XtNumber (arr)       ((Cardinal)     (sizeof(arr)    /   sizeof  (arr [0] ) ) ) 

See  Also 

XtOffset(\\  XtOffsetOf(\\  XtSetArg(\). 
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XtOffset  \ v 

v Xt  -  Argument  Lists— 

Name 

XtOffset  —  determine  the  byte  offset  of  a  field  within  a  structure  pointer  type. 

Synopsis 

Cardinal   XtOf f set (point er_typer    field_name) 
Type  point er_type; 
Field   field_name; 

Arguments 

pointer_type      Specifies  a  type  that  is  declared  as  a  pointer  to  the  structure. 

f  i  el  d_name          Specifies  the  name  of  the  field  for  which  to  calculate  the  byte  offset. 

Description 

XtOffset  computes  the  relative  address  of  a  field  in  bytes,  given  a  pointer  to  a  structure. 
Using  XtOffset,  a  program  can  use  field  names,  instead  of  numeric  byte  offsets,  to  specify 
addresses  in  a  structure  relative  to  a  base  pointer.  XtOffset  can  be  used  at  compile  time  in 
static  initializations. 

XtOffset  is  often  used  to  determine  the  location  of  an  instance  variable  in  a  widget  record. 
Resource  fields  are  defined  in  terms  of  offsets  from  a  base  address  from  the  beginning  of  a 
widget  Thus,  a  resource  value  can  be  kept  up  to  date  by  the  Resource  Manager  without  any 
knowledge  of  the  instance  structure  of  the  widget;  it  uses  just  a  relative  byte  offset. 

XtOffset  is  less  portable  than  XtOf  f  setOf . 

The  following  code  uses  XtOffset  to  define  the  foreground  resource  in  the  Athena  Label 
widget 

static  XtResource   resources []    =    { 
{ 

XtNforeground,  /*    Resource   name    is    foreground    */ 

XtCForeground,  /*    Resource   class    is   Foreground    *'/ 

XtRPixel,  /*   Resource  type   is   Pixel    */ 

sizeof (Pixel) ,  /*   allocate   enough   space   to  hold  a  Pixel   value    */ 

XtOf f set (LabelWidget,    label . foreground) , /*where   in   instnce   strct*/ 
XtRString,  /*Default   val   is   a   String    (will   need  conversion) */ 

XtDef aultForeground      /*    Default   address    */ 


XtOffset  is  a  macro  defined  in  <X1  II Intrinsic. h>  as  follows: 

tdefine   XtOf f set (type, field)       ((unsigned   int)     (((char    *)    \ 
(&  (  (  (type)  NULL) ->field)  )  )  —  (  (char    *)    NULL))) 

See  Also 

XtGetResources(\\  XtOffsetOf(\\ 
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t .'     f  XtOff  setOf 

— Xt  -  Argument  Lists ' 

Name 

XtOffsetOf  —  determine  the  byte  offset  of  a  field  within  a  structure  type. 

Synopsis 

Cardinal  XtOf f setOf (structure_type,  field_name) 
Type  structure_type; 
Field  field_name; 

Arguments 

struct ure_type 

Specifies  a  type  that  is  declared  as  a  structure. 
f  i  el  d_name        Specifies  the  name  of  a  member  within  the  structure. 

Description 

The  XtOffsetOf  macro  expands  to  a  constant  expression  that  gives  the  offset  in  bytes  to  the 
specified  structure  member  from  the  beginning  of  the  structure.  It  is  normally  used  to  statically 
initialize  resource  lists  and  is  more  portable  than  XtOf  f  set,  which  serves  the  same  function. 

See  Also 

XtOffset(l) 
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XtOpenDJsplay  \ 

v Xt  -  Application  Contexts— 

Name 

XtOpenDisplay  —  open,  initialize,  and  add  a  display  to  an  application  context. 

Synopsis 

Display  *XtOpenDisplay (app_ context,  display_name,  application_name,  appli- 

cation_class,  options,  num_options,  argc,  argv) 
XtAppContext  app_context; 
String  display_name; 
String  application_name; 
String  application_class; 
XrmOptionDescRec  * opt  ions; 
Cardinal  num_options; 
Cardinal  *argc; 
String  *argv; 

Arguments 

app_context      Specifies  the  application  context. 

display_name    Specifies  the  display.  A  display  can  be  in  at  most  one  application  context. 

app 1 icati on_name 

Specifies  the  name  of  the  application  instance. 

application_class 

Specifies  the  class  name  of  this  application,  which  is  usually  the  generic 
name  for  all  instances  of  this  application. 

options  Specifies   how  to  parse  the  command  line  for  any  application-specific 

resources.  The  options  argument  is  passed  as  a  parameter  to  XrmParse- 
Command.  For  further  information,  see  XtlnitializeDisplay. 

num_options      Specifies  the  number  of  entries  in  the  options  list. 

argc  Specifies  a  pointer  to  the  number  of  command  line  parameters. 

argv  Specifies  the  command  line  parameters. 

Description 

XtOpenDisplay  can  be  used  to  open  a  display  (possibly  an  additional  display)  and  add  it  to 
an  application  context. 

The  XtOpenDisplay  function  calls  XOpenDisplay  with  the  specified  display  name.  If 
display_/7a/ne  is  NULL,  XtOpenDisplay  uses  the  current  value  of  the  -display  option 
specified  in  argv  and  if  no  display  is  specified  in  argv,  uses  the  user's  default  display  (on 
POSIX-based  systems,  this  is  the  value  of  the  DISPLAY  environment  variable). 

If  this  succeeds,  it  then  calls  XtDisplaylnitialize  and  passes  it  the  opened  display  and 
the  value  of  the  -name  option  specified  in  argv  as  the  application  name.  If  no  name  option  is 
specified  and  application_name  is  non-NULL,  then  application_name  is  passed  to 
XtDisplaylnitialize.  If  application_name  is  NULL  and  if  the  environment  vari 
able  RESOURCE_NAME  is  set,  the  value  of  RESOURCE.NAME  is  used.  Otherwise,  the  applica 
tion  name  is  the  name  used  to  invoke  the  program.  On  implementations  that  conform  to  ANSI  C 
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Hosted  Environment  support,  the  application  name  will  be  equal  to  argv[0]  less  any  direc 
tory  and  file  type  components;  that  is,  the  final  component  of  argv[0],  if  specified.  If 
argv[0]  does  not  exist  or  is  the  empty  string,  the  application  name  is  "main".  XtOpen 
Display  returns  the  newly  opened  display  or  NULL  if  it  failed. 

XtApplnitialize  opens  one  display.  Application  contexts  are  constructed  with  Xt- 
CreateApplicationContext.  Parsing  the  command  line  is  discussed  in  XtDisplay- 
Initialize(l).  There  is  example  code  in  Chapter  9,  Resource  Management  and  Type  Con 
version,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 

See  Also 

XtApplnitialize  ( 1 ),  XtDisplaylnitialize  ( 1 ). 
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XtOverrideTranslations 

•Xt  -  Translations  and  Actions— 

Name 

XtOverrideTranslations  —  merge  new  translations,  overwriting  widget's  existing  ones. 

Synopsis 

void  XtOverrideTranslations (w,  translations) 
Widget  w; 
XtTranslations  translations; 

Arguments 

vi  Specifies  the  widget  into  which  the  new  translations  are  to  be  merged. 

translations       Specifies  the  compiled  translation  table  to  merge  in  (must  not  be  NULL). 

Description 

XtOverrideTranslations  merges  new  translations  into  the  existing  widget  translations, 
overriding  the  translations  for  any  event  or  event  sequence  that  already  exists  in  the  widget's 
translations,  and  possibly  adding  new  ones.  XtOverrideTranslations  ignores  any 
treplace,  #augment  or  ^override  directive  that  may  have  been  specified  in  the  transla 
tion  string. 

The  translation  table  must  be  in  compiled  form,  as  produced  by  xtParseTranslation- 
Table.  XtParseTranslationTable  produces  the  binary  form  of  the  translation  table 
from  text.  XtConvertAndStore  can  also  do  this,  specifying  XtRTranslationTable  as 
the  destination  resource  type.  (A  text  translation  table  is  automatically  parsed  in  the  Core 
widget  structure  when  a  widget  class  is  initialized.) 

To  make  it  easy  to  modify  translation  tables  in  resource  files,  the  string-to-translation-table 
resource  type  converter  allows  you  to  specify  whether  the  table  should  replace,  augment,  or 
override  any  existing  translation  table  in  the  widget  As  an  option,  a  pound  sign  (#)  as  the  first 
character  of  the  table  followed  by  replace  (default),  augment,  or  override  indicates  how 
to  treat  existing  translations. 

The  replace  or  merge  operation  is  performed  during  the  Core  instance  initialization  and  during 
the  Core  set_values  invocation.  At  instance  initialization  the  widget  class  translation  table 
(if  any)  is  copied  into  the  widget  prior  to  a  merge  operation.  The  merge  operation  produces  a 
new  translation  resource  value;  if  the  original  table  was  shared  by  other  widgets,  they  are  unaf 
fected. 

To  merge  new  translations,  but  keep  existing  translations  in  case  of  conflict,  use  Xt Augment - 
Translations. 

To  replace  a  widget's  translations  completely  and  not  just  selectively  overwrite  some  of  them, 
use  XtSetValues  on  the  XtNtranslations  resource  and  specify  a  compiled  translation 
table  as  the  value. 

To  completely  remove  existing  translations,  use  xtUninstallTranslations. 
See  Also 

XtA ugmenfTronslations ( 1 ),  XtConvertAndStore ( 1 ),  XtParseTranslationTable  ( 1 ), 
\  Text(5). 
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— Xt- Selections - 


J  XtOwnSelection 


Name 

XtOwnSelection  —  indicate  that  selection  data  is  available. 

Synopsis 

Boolean  XtOwnSelection (w,  selection,  time,  convert_proc,  lose_proc, 

done_proc) 
Widget  w; 
Atom  selection; 
Time  time; 

Xt Con vert Selection? roc  convert _proc; 
XtLoseSelectionProc  lose_proc; 
XtSelectionDoneProc  done_proc; 

Arguments 

w  Specifies  the  widget  that  wishes  to  become  the  owner. 

selection  Specifies  an  atom  that  describes  the  type  of  the  selection  (for  example, 
XA_PRIMARY,  XA_SECONDARY;  these  two  are  declared  beforehand  in 
<Xll/Xatom.h>). 

time  Specifies  the  times  when  selection  ownership  should  commence.  This  should 

be  the  timestamp  of  the  event  that  triggered  ownership.  It  should  be  the 
time  field  taken  directly  from  an  XEvent  structure.  The  value  Cur  rent - 
Time  is  not  acceptable. 

convert_proc  Specifies  the  procedure  to  call  whenever  someone  requests  the  current  value 
of  the  selection. 

lose_proc  Specifies  the  procedure  to  call  whenever  the  widget  has  lost  selection  owner 
ship,  or  specifies  NULL  if  the  owner  is  not  interested  in  being  called  back. 

donejproc  Specifies  the  procedure  to  call  after  the  transfer  completes,  or  specifies  NULL 
if  the  owner  is  not  interested  in  being  called  back. 

Description 

Calling  XtOwnSelection  is  a  precursor  to  sending  data  through  the  selection  mechanism. 
XtOwnSelection  informs  the  Intrinsics  of  its  claim  on  the  selection,  and  its  readiness  to 
send  data  on  request  XtOwnSelection  returns  True  if  the  widget  has  successfully  become 
the  owner  and  False  otherwise. 

The  widget  may  fail  to  become  the  owner  if  some  other  widget  has  asserted  ownership  after  this 
widget,  as  indicated  by  time.  Widgets  can  lose  selection  ownership  either  because  another 
client  more  recently  asserted  ownership  of  the  selection,  or  because  the  widget  voluntarily  gave 
up  ownership  of  the  selection  with  XtDisownSelection. 

The  lose_proc  procedure  is  invoked  when  another  widget  successfully  claims  the  selection 
after  w.  The  1  ose_proc  procedure  is  not  called  if  the  widget  fails  to  obtain  selection  owner 
ship  in  the  first  place. 

If  the  widget  successfully  obtains  the  selection  ownership,  subsequent  requests  for  data  will  be 
directed  to  convert_jproc. 
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XtOwnSeleCtion  (continued)  Xt  -  Selections 

xtConvertSelectionProc(2)  describes  the  responsibilities  of  the  widget  or  application 
sending  data  and  its  conversion  duties.  Chapter  10,  Interdient  Communications,  in  Volume 
Four,  X  Toolkit  Intrinsics  Programming  Manual,  presents  a  complete  example  widget  that  both 
sends  and  receives  data  using  selection. 

See  Also 

XtDisownSelection ( 1 ),  XtGetSelectionValue(\\ 

XtConvertSetectionProc(2),  XtLoseSelectionProc(2),  XtSelectionDoneProc(2). 
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—Xt- Selections- 


XtOwnSelectionlncremental 


Name 

XtOwnSelectionlncremental  —  set  the  selection  owner  when  using  incremental  transfers. 

Synopsis 

Boolean   XtOwnSelectionlncremental (w,    selection,    time,    convert_callback, 

lose_callback,    done_callback,    cancel_callback,    client_data) 
Widget    w; 
Atom   selection; 
Time    time; 

XtConvert Select ion IncrProc   convert _callback; 
Xt Lose Select ion IncrP roc   lose_cal Iback; 
XtSelectionDone IncrProc   done_cal Iback; 
XtCancelConvertSelectionProc   cancel_cal Iback; 
XtPointer   client   data; 


Arguments 

w 


selection 


time 


Specifies  the  widget  that  wishes  to  become  the  owner. 

Specifies  an  atom  that  names  the  selection  (for  example,  XA_PRIMARY, 
XA_SECONDARY,  or  CLIPBOARD). 

Specifies  the  timestamp  that  indicates  when  the  selection  ownership 
should  commence.  This  should  be  the  timestamp  of  the  event  that  trig 
gered  ownership;  the  value  CurrentTime  is  not  acceptable. 

convert_callback  Specifies  the  procedure  that  is  to  be  called  whenever  the  current  value  of 
the  selection  is  requested. 

Specifies  the  procedure  that  is  to  be  called  whenever  the  widget  has  lost 
selection  ownership  or  NULL  if  the  owner  is  not  interested  in  being  noti 
fied. 


2ose   callback 


done   callback 


cancel    callback 


client   data 


Specifies  the  procedure  that  is  called  after  the  requestor  has  received,  the 
entire  selection  or  NULL  if  the  owner  is  not  interested  in  being  notified. 

Specifies  the  procedure  that  is  to  be  called  when  a  selection  request 
aborts  because  a  timeout  expires,  or  NULL  if  the  owner  is  not  interested  in 
being  notified. 

Specifies  the  argument  that  is  to  be  passed  to  each  of  the  callback  proce 
dures  when  they  are  called. 


Description 

When  using  the  incremental  interface,  an  owner  may  have  to  process  more  than  one  selection 
request  for  the  same  selection,  converted  to  the  same  target,  at  the  same  time.  The 
request_id  argument  is  guaranteed  to  be  unique  among  all  incremental  requests  that  are 
active  concurrently. 

The  XtOwnSelectionlncremental  procedure  informs  the  Intrinsics  incremental  selec 
tion  mechanism  that  the  specified  widget  wishes  to  own  the  selection.  It  returns  True  if  the 
specified  widget  successfully  becomes  the  selection  owner  or  False  otherwise. 
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XtOwnSelectionlncremental  (continued)  Xt- Selections 

If  a  done_callback  is  specified,  the  client  owns  the  storage  allocated  for  passing  the  value 
to  the  Intrinsics.  If  done_callback  is  NULL,  the  convert_callback  must  allocate  stor 
age  using  xtMalloc,  xtRealloc  or  xtCalloc  and  the  final  value  specified  will  be  freed 
by  the  Intrinsics  when  the  transfer  is  complete.  After  a  selection  transfer  has  started,  only  one 
of  the  don e_ callback  or  cancel_callback  procedures  will  be  invoked  to  indicate 
completion  of  the  transfer. 

The  lose_callback  does  not  indicate  completion  of  any  in-progress  transfers;  it  will  be 
invoked  at  the  time  a  SelectionClear  event  is  dispatched  regardless  of  any  active 
transfers,  which  are  still  expected  to  continue. 

A  widget  that  becomes  the  selection  owner  using  XtOwnSelectionlncremental  may  use 
XtDisownSelection  to  relinquish  selection  ownership. 

See  Also 

XtAppGetSelectionTimeout(\\  XtAppSetSelectionTimeout(\),  XtDisownSelection(\\  XtGetSelection- 
Request(l),  XtGetSelectionTimeout(l\  XtGetSelectionVolue(\\  XtGetSelectionValueIncremental(\\  Xt- 
GetSelectionValues(l),  XtGetSelectionValuesIncremental(\),  XtO\vnSelection(\\  XtSetS election- 
Timeout^). 
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..   J  XtParent 

— Xt  -  Object  Information ' 

Name 

XtParent  —  return  the  parent  widget  for  the  specified  widget. 

Synopsis 

Widget  XtParent (w) 
Widget  w; 

Arguments 

w  Specifies  the  widget  whose  parent  is  to  be  returned. 

Description 

XtParent  returns  the  parent  widget  of  the  specified  widget.  The  return  value  may  be  of  class 
Object  or  any  subclass. 
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XtParseAcceleratorTable  _, 

v Xt  -  Translations  and  Actions — 

Name 

XtParseAcceleratorTable  —  compile  an  accelerator  table  into  its  internal  representation. 

Synopsis 

XtAccelerators  XtParseAcceleratorTable (table) 
String  table; 

Arguments 

table  Specifies  the  accelerator  table  to  compile. 

Description 

XtParseAcceleratorTable  compiles  the  accelerator  table  into  its  opaque  internal  repre 
sentation.  This  compiled  table  is  then  used  to  set  the  xtNaccelerators  resource  of  a 
widget  in  the  application  code.  When  an  accelerator  table  is  specified  in  a  resource  file,  it  is 
automatically  parsed  by  one  of  Xt's  converters,  and  XtParseAcceleratorTable  is  not 
used. 

Another  way  to  parse  an  accelerator  table  is  to  use  the  xtRString-to-xtRAccelerator- 
Table  converter  with  the  XtVaTypedArg  feature  at  xtVaCreateWidget  or  XtVaSet- 
Values. 

Accelerators  can  be  specified  in  defaults  files,  and  the  string  representation  is  the  same  as  for  a 
translation  table.  However,  the  interpretation  of  the  #augment  and  toverride  directives 
applies  to  what  will  happen  when  the  accelerator  is  installed;  that  is,  whether  or  not  the  acceler 
ator  translations  will  override  the  translations  in  the  destination  widget.  The  default  is 
# augment,  which  means  that  the  accelerator  translations  have  lower  priority  than  the  destina 
tion  translations.  The  # replace  directive  is  ignored  for  accelerator  tables. 

An  accelerator,  once  installed,  binds  an  event  sequence  in  one  widget  (called  the  destination)  to 
actions  in  another  (called  the  source).  An  accelerator  table  is  similar  to  a  translation  table  in 
appearance.  Accelerators  that  are  set  as  a  resource  of  the  source  widget  dp  not  take  effect  until 
they  are  installed  on  the  destination  widget 

Each  class  of  widget  has  a  display_accelerator  method  to  which  Xt  passes  a  display- 
able  string  representation  of  the  accelerators  so  that  widgets  can  display  their  current  accelera 
tors.  The  representation  is  the  accelerator  table  in  canonical  translation  table  form  (see  Appen 
dix  F,  Translation  Table  Syntax). 

For  more  information,  see  Chapter  7,  Events,  Translations,  and  Accelerators,  in  Volume 
Four,  X  Toolkit  Intrinsics  Programming  Manual. 

See  Also 

XtlnstallAccelerators ( 1 ),  XtlnstcdlAllAccelerators(\ ), 
display  jaccelerator  (4). 
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— Xt  -  Translations  and  Actions ' 

Name 

XtParseTranslationTable  —  compile  a  translation  table  into  its  internal  representation. 

Synopsis 

XtTranslations  XtParseTranslationTable (table) 
String  table; 

Arguments 

table  Specifies  the  translation  table  to  compile. 

Description 

XtParseTranslationTable  compiles  table  into  its  opaque  internal  representation  of 
type  XtTranslations.  This  function  is  needed  when  setting  a  translation  table  resource 
from  the  application.  In  widget  code,  the  default  translation  table  is  automatically  parsed. 

A  translation  table  is  a  string  containing  a  list  of  translations,  each  of  which  maps  an  event 
sequence  into  one  or  more  action  procedure  calls.  The  translations  are  separated  from  one 
another  by  newline  characters  (ASCII  LF).  The  complete  syntax  of  translation  tables  is  speci 
fied  in  Appendix  F,  Translation  Table  Syntax.  All  widget  instance  records  contain  a  translation 
table,  which  is  a  resource  with  no  default  value. 

As  an  example,  the  default  behavior  of  the  Athena  Command  widget  is: 

•  Highlight  on  enter  window. 

•  Unhighlight  on  exit  window. 

•  Invert  on  left  button  down. 

•  Call  callbacks  and  reinvert  on  left  button  up. 

The  following  illustrates  the  Command  widget's  default  translation  table: 

static  String  defaultTranslations  = 

"<EnterWindow> :  Highlight ( ) \n\ 
<LeaveWindow>:   Unhighlight () \n\ 
<BtnlDown> :     Set ( ) \n\ 
<BtnlUp>:       Notify  ()  Unset  ()"; 

The  tm_table  field  of  the  CoreClass  record  should  be  filled  in  at  static  initialization  time 
with  the  string  containing  the  class'  default  translations.  If  a  class  wants  to  inherit  its  super 
class'  translations,  it  can  store  the  special  value  XtlnheritTranslations  into 
tm_table.  After  the  class  initialization  procedures  have  been  called,  the  Intrinsics  compile 
this  translation  table  into  an  efficient  internal  form.  Then,  at  widget  creation  time,  this  default 
translation  table  is  used  for  any  widgets  that  have  not  had  their  core  translations  field  set  by  the 
Resource  Manager  or  the  initialize  methods. 

The  resource  conversion  mechanism  automatically  compiles  translation  tables  that  are  set  in 
resource  files. 

Widgets  need  do  nothing  other  than  specify  the  action  and  translation  tables  for  events  to  be 
processed  by  the  Translation  Manager. 
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The  facility  to  parse  translation  tables  can  also  be  accessed  by  converting  a  string  resource  into 
a  resource  of  type  xtRTranslationTable.  One  convenient  way  to  do  this  is  to  use  the 
XtVaTypedArg  feature  of  XtVaCreateWidget  and  XtVaSetValues.  If  an  empty 
translation  table  is  required  for  any  purpose,  one  can  be  obtained  by  calling  XtParse 
TranslationTable  and  passing  an  empty  string. 

XtAugmentTranslations  and  XtOverrideTranslations  both  expect  translations  in 
compiled  form.  For  more  information,  see  Chapter  7,  Events,  Translations,  and  Accelerators, 
in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 

See  Also 

XtAugmenfTranslations ( 1 ),  XtOverrideTranslations ( 1 ),  XtUninstallTranslations ( 1 ). 
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-X,  -  Ev.n«  HandUng /  XtPeekEvent 

Name 

XtPeekEvent  —  nondestructively  examine  the  head  of  an  application's  input  queue. 

Synopsis 

Boolean  XtPeekEvent (event_return) 
XEvent  * even t_re turn; r 

Arguments 

event_return         Returns  the  event  information  from  the  head  event  structure  in  the  queue. 

Description 

XtPeekEvent  has  been  superseded  by  XtAppPeekEvent.  XtPeekEvent  returns  the  old 
est  event  on  the  event  queue,  but  does  not  remove  the  event  from  the  queue. 

Programs  rarely  need  this  much  control  over  the  event  dispatching  mechanism.  Most  programs 
use  XtAppMainLoop. 

See  Also 

XtAppMainLoop  (1),  XtAppPeekEvent(l),  XtAppP  ending  (I). 
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XtPending  \ 

v Xt  -  Event  Handling  — 

Name 

XtPending  —  determine  if  there  are  any  events  in  an  application's  input  queue. 

Synopsis 

XtlnputMask  XtPending () 

Description 

XtPending  has  been  superseded  by  XtAppPending.  XtPending  returns  a  mask  indicat 
ing  which  types  of  input  are  currently  pending. 

XtAppPending  returns  a  nonzero  value  if  there  are  pending  events  from  the  X  server,  timer, 
or  other  input  sources.  The  return  value  is  a  bit  mask  that  is  the  OR  of  xtlMXEvent  (an  X 
event),  xtlMTimer  (a  timer  event  introduced  onto  the  queue  by  a  call  to  XtAppAddTime- 
Out),  and  XtlMAlternatelnput  (an  alternate  input  event  introduced  onto  the  queue  by  a 
call  to  xtAppAddlnput).  As  a  convenience,  the  symbolic  name  xtlMAll  is  defined  as  the 
bitwise  inclusive  OR  of  all  event  types.  If  no  events  are  pending,  XtAppPending  flushes  the 
output  buffers  of  each  display  in  the  application  context  and  returns  zero.  This  call  is  the 
Intrinsics  equivalent  to  the  Xlib  call  XPending. 

Programs  rarely  need  this  much  control  over  the  event  dispatching  mechanism.  Most  programs 
use  XtAppMainLoop. 

See  Also 

XtAppMainLoop  (1),  XtAppPeekEvent(\),  XtAppPending  (I). 
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J  XtPopdown 


Name 

XtPopdown  —  unmap  a  pop-up  shell. 

Synopsis 

void  XtPopdown (popup_shell) 
Widget  popup_shell; 

Arguments 

popup_shel  1      Specifies  the  widget  shell  to  pop  down. 

Description 

XtPopdown  pops  down  a  pop-up  shell  that  was  popped  up  by  xt Popup  or  xtPopup- 
SpringLoaded,  by  one  of  the  built-in  callback  functions  (XtCallbackExclusive,  Xt- 
CallbackNonexclusive,  or  XtCallbackNone),  or  by  the  built-in  action  function  xt- 
MenuPopup. 

To  perform  a  pop  down  from  a  callback  list,  use  xtCallbackPopdown.  To  do  so  from  a 
translation  table,  use  XtMenuPopdown. 

XtPopdown  performs  the  following: 

•  Calls  xtCheckSubclass  to  ensure  popup_shell  is  a  subclass  of  Shell. 

•  Checks  that  popup_shell  is  currently  popped_up;  otherwise,  it  generates  an  error. 

•  Unmaps  popup_shel  1  's  window. 

•  If  popup_shell's  grab_kind  is  either  XtGrabNonexclusive  or  XtGrab- 
Exclusive,  it  calls  xtRemoveGrab.  The  grab  kind  is  specified  as  an  argument  to 
XtPopup. 

•  Sets  popup_shellts  popped_up  field  to  False. 

•  Calls  the  callback  procedures  on  the  shell's  popdown_callback  list,  designated  by 
the  resource  XtNpopdownCallback.  (See  XtCreatePopupShell.) 

Pop-up  shell  widgets  can  be  created  with  XtCreatePopupShell.  For  more  information, 
see  Chapter  12,  Menus,  Gadgets,  and  Cascaded  Pop  Ups,  in  Volume  Four,  X  Toolkit  Intrinsics 
Programming  Manual. 

See  Also 

XtCallbackPopdown(\\  XtCheckSubclass(l),  XtCreatePopupSheIl(\),  XtMenuPopdown(l),  XtRemove- 
Grab(l). 
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XtPopup  \ Yi 

> Xt  -  Pop  Ups— 

Name 

XtPopup  —  map  a  pop-up  shell. 

Synopsis 

void  XtPopup  (popup_shellr    grab_kind) 
Widget  popup_shell; 
XtGrabKind   grab_kind; 

Arguments 

popup_sheli      Specifies  a  widget  shell  returned  by  xtCreatePopupShell. 

grab_kind         Specifies  how  user  events  should  be  constrained.  (Can  be  one  of  xtGrab- 
None,  XtGrabNonexclusive,  XtGrabExclusive.) 

Description 

After  creating  a  pop-up  shell  with  XtCreatePopupShell  and  its  managed  child  with  Xt- 
CreateManagedWidget,  the  pop  up  is  ready  to  be  mapped  to  the  display.  The  easiest  way 
to  map  the  pop  up  from  the  application  code  is  with  XtPopup  or  xtPopupSpringLoaded. 

XtPopup  maps  its  window,  by  default,  to  the  upper-left  comer  of  the  display.  This  can  be  cir 
cumvented  by  relocating  the  pop-up  shell  with  xtMoveWidget  before  calling  XtPopup. 

XtPopup  performs  the  following  actions: 

•  Calls  XtCheckSubclass  to  ensure  popup_shell  is  a  subclass  of  Shell. 

•  Returns  if  the  shell  is  already  popped  up. 

•  Calls  the  callback  procedures  on  the  shell's  pop-up  callback  list,  designated  by  the 
resource  XtNpopupCallback.  (See  XtCreatePopupShell.) 

•  Sets  the  shell  popped_up  field  to  True,  the  shell  spring_loaded  field  to  False, 
and  the  shell  grab_kind  field  to  grab_kind.  grab_kind  specifies  the  grab  type 
inserted  in  the  modal  cascade.  (See  xtAddGrab.) 

•  If  the  shell's  create_popup_child  field  is  non-NULL,  XtPopup  calls  the  designated 
function  with  popup_shell  as  the  parameter.  This  field  is  designated  by  the  resource 
XtNcreatePopupChildProc.  (See  XtCreatePopupShell). 

•  If  grab_kind  is  either  XtGrabNonexclusive  or  XtGrabExclusive,  it  calls: 

XtAddGrab (popup_shell,     (grab_kind  ==  XtGrabExclusive),    False) 

•  Calls  XtRealizeWidget  with  popup_shell. 

•  Calls  XMapRaised  with  the  Core  window  field  from  popup_shell. 

Widgets  can  be  popped  down  with  xtPopdown.  For  more  specifics  on  how  to  relocate  the 
pop-up  shell  before  popping  it  up,  see  XtMoveWidget  and  XtTranslateCoords.  To  per 
form  a  pop  up  from  a  callback  list,  see  XtCallbackNone,  xtCallbackNonexclusive, 
and  xtCallbackExclusive.  To  do  so  from  a  translation  table,  use  xtMenuPopup.  For 
details  on  how  events  are  constrained  to  the  pop  up,  see  XtAddGrab. 
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(continued) 


XtPopup 


For  more  information,  see  Chapter  12,  Menus,  Gadgets,  and  Cascaded  Pop  Ups,  in  Volume 
Four,  X  Toolkit  Intrinsics  Programming  Manual. 

See  Also 

XtCheckSubclass(\\  XtCreateManagedWidget(\\  XtPopupSpringLoaded(\\  XtRealizeWidget(l). 
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XtPopupSpringLoaded  \ 


Name 

XtPopupSpringLoaded  —  map  a  spring-loaded  pop-up  from  within  an  application. 

Synopsis 

void  XtPopupSpringLoaded (popup_shell) 
Widget  popup_shell; 

Arguments 

popup_sheii      Specifies  the  shell  widget  to  be  popped  up. 

Description 

XtPopupSpringLoaded  performs  exactly  like  XtPopup,  except  that  XtPopupSpring 
Loaded  does  the  following: 

•  Sets  the  shell  spring_l oaded  field  to  True. 

•  Always  calls  XtAddGrab  with  exclusive  set  to  True  and  spring_loaded  set  to 
True. 

See  Also 

XtAddGrob(\\  XtCollbackExclusive(l),  XtCallbackNone(l\  XtCallbackNonexclusive(l)t  XtCallback- 
Popdown(\\  XtCreatePopupShell(\\  XtMenuPopdown,  XtMenuPopup,  XtPopdo\vn(\\  XtPopup(l),  Xt- 
RemoveGrab(l),XtVaCreatePopupShell(l). 
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XtProcessEvent 


Name 

XtProcessEvent  —  process  one  input  event 

Synopsis 

void  XtProcessEvent (mask) 
Xt Input Mask  mask; 

Arguments 

mask  Specifies  what  types  of  events  to  process.  The  mask  is  the  bitwise  inclusive 

OR  of  XtlMXEvent  (an  X  event),  XtlMTimer  (a  timer  event),  or  xt- 
iMAlternatelnput  (an  alternate  input  event).  The  symbolic  constant 
xtlMAll  is  the  bitwise  inclusive  OR  of  all  input  types. 

Description 

XtProcessEvent  has  been  superseded  by  XtAppProcessEvent.   XtProcessEvent 
gets  one  event  of  any  of  the  types  specified  in  mask  and  dispatches  it. 

Programs  rarely  need  this  much  control  over  the  event  dispatching  mechanism.  Most  programs 
use  XtAppMainLoop. 

See  Also 

XtAppPeekEvent(\\  XtAppPending(l),  XtAppProcessEvent(l). 
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XtQueryGeometry  _ 

> Xt  -  Geometry  Management- 
Name 

XtQueryGeometry  —  query  a  child  widget's  preferred  geometry. 

Synopsis 

XtGeometryResult  XtQueryGeometry (wr  intended,  preferred_return) 
Widget  w; 

XtWidgetGeometry  *intended; 
Xt Widget Geometry  *preferred_return; 

Arguments 

w  Specifies  the  widget  whose  geometry  preferences  are  being  queried. 

intended  Specifies  any  changes  the  parent  plans  to  make  to  the  child's  geometry,  or 

NULL. 

preferred_ret urn 

Returns  the  child  widget's  preferred  geometry. 

Description 

Some  parents  may  be  willing  to  adjust  their  layouts  to  accommodate  the  preferred  geometries 
of  their  children.  They  can  use  XtQueryGeometry  to  obtain  the  preferred  geometry  and,  as 
they  see  fit,  can  use  or  ignore  any  portion  of  the  response. 

To  discover  a  child's  preferred  geometry,  the  child's  parent  stores  the  new  geometry  in  the  cor 
responding  fields  of  the  intended  structure,  sets  the  corresponding  bits  in 
intended.  request_mode,  and  calls  XtQueryGeometry.  The  parent  should  set  only 
those  fields  that  are  important  to  it  so  the  child  can  determine  whether  it  may  be  able  to  attempt 
changes  to  other  fields. 

XtQueryGeometry  clears  all  bits  in  the  preferred_return->request_mode  and 
checks  the  query_geometry  field  of  the  specified  widget's  class  record.  If  the  widget's 
query_geometry  method  is  not  NULL,  XtQueryGeometry  calls  the  query_geometry 
method  and  passes  w,  intended,  and  preferred_return  as  arguments.  If  intended  is 
NULL,  XtQueryGeometry  replaces  it  with  a  pointer  to  an  XtWidgetGeometry  structure 
with  request_mode=0  before  calling  query_geometry. 

If  XtQueryGeometry  is  called  from  within  a  geometry_manager  procedure  for  the 
widget  that  issued  XtMakeGeometryRequest  or  XtMakeResizeRequest,  the  results 
are  not  guaranteed  to  be  consistent  with  the  requested  changes.  The  change  request  passed  to 
the  geometry  manager  takes  precedence  over  the  preferred  geometry. 

The  query_geometry  procedure  pointer  is  of  type  Xtquery_geometry. 

The  query_geometry  procedure  is  expected  to  examine  the  bits  set  in 
request->request_mode,  evaluate  the  preferred  geometry  of  the  widget,  and  store  the 
result  in  geometry_return  (setting  the  bits  in  geometry_return->request_mode 
corresponding  to  those  geometry  fields  that  it  cares  about).  If  the  proposed  geometry  change  is 
acceptable  without  modification,  the  query_geometry  procedure  should  return  Xt- 
GeometryYes.  If  at  least  one  field  in  geometry_return  with  a  bit  set  in 
geometry_return->request_mode  is  different  from  the  corresponding  field  in  request 
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or  if  a  bit  was  set  in  geometry_return->request_mode  that  was  not  set  in  the  request, 
the  query_geometry  procedure  should  return  XtGeometryAlmost.  If  the  preferred 
geometry  is  identical  to  the  current  geometry,  the  query_geometry  procedure  should  return 
Xt Geomet  ryNo. 

The  query_geometry  procedure  may  assume  that  no  xtMakeResizeRequest  or  Xt- 
MakeGeometryRequest  is  in-progress  for  the  specified  widget;  that  is,  it  is  not  required  to 
construct  a  reply  consistent  with  the  requested  geometry  if  such  a  request  were  actually  out 
standing. 

After  calling  the  query_geometry  procedure  or  if  the  query_geometry  field  is  NULL, 
XtQueryGeometry  examines  all  the  unset  bits  in  geometry_return->request_mode 
and  sets  the  corresponding  fields  in  geometry_return  to  the  current  values  from  the  widget 
instance.  If  the  request_mode  field  is  not  set  to  CWStackMode,  the  stack_mode  field  is 
set  to  XtSMDont Change.  XtQueryGeometry  returns  the  value  returned  by  the 
query_geometry  procedure  or  XtGeometryYes  if  the  query_geometry  field  is  NULL. 

Therefore,  the  caller  can  interpret  a  return  of  XtGeometryYes  as  not  needing  to  evaluate  the 
contents  of  the  reply  and,  more  importantly,  not  needing  to  modify  its  layout  plans.  A  return  of 
XtGeometryAlmost  means  either  that  both  the  parent  and  the  child  expressed  interest  in  at 
least  one  common  field  and  the  child's  preference  does  not  match  the  parent's  intentions  or  that 
the  child  expressed  interest  in  a  field  that  the  parent  might  need  to  consider.  A  return  value  of 
XtGeometryNo  means  that  both  the  parent  and  the  child  expressed  interest  in  a  field  and  that 
the  child  suggests  that  the  field's  current  value  is  its  preferred  value.  In  addition,  whether  or 
not  the  caller  ignores  the  return  value  or  the  reply  mask,  it  is  guaranteed  that  the  reply  structure 
contains  complete  geometry  information  for  the  child. 

Parents  are  expected  to  call  XtQueryGeometry  in  their  layout  routine  and  wherever  other 
information  is  significant  after  change_managed  has  been  called.  The  change_managed 
method  may  assume  that  the  child's  current  geometry  is  its  preferred  geometry.  Thus,  the  child 
is  still  responsible  for  storing  values  into  its  own  geometry  during  its  initialize  method. 

Structures 

The  return  codes  from  geometry  managers  are: 

typedef  enum  { 

XtGeometryYes,    /*  Request  accepted  */ 

XtGeometryNo,     /*  Request  denied  */ 

XtGeometryAlmost,/*  Request  denied  but  willing  to  take  reply  */ 

XtGeometryDone    /*  Request  accepted  and  done  */ 
}  XtGeometryResult; 

The  XtwidgetGeometry  structure  is  similar  to  but  not  identical  to  the  corresponding  Xlib 
structure: 

typedef  unsigned  long  XtGeometryMask; 

typedef  struct  { 

XtGeometryMask  request_mode; 
Position  x,  y; 
Dimension  width,  height; 
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Dimension   border_width; 
Widget    sibling; 
int    stack_mode; 
}    XtWidgetGeometry; 

The  request_mode  definitions  are  from  <XlllX.h>: 


#def  ine 

CWX 

(1«0) 

#def  ine 

CWY 

(1«1) 

#def  ine 

CWWidth 

d«2) 

#define 

CWHeight 

d«3) 

#define 

CWBorderWidth 

(1«4) 

tdefine 

CWSibling 

d«5) 

#define 

CWStackMode 

d«6) 

The  Xt  Intrinsics  also  support  the  following  value: 

tdefine         XtCWQueryOnly  (1«7) 

XtCWQueryOnly  indicates  that  the  corresponding  geometry  request  is  only  a  query  as  to  what 
would  happen  if  this  geometry  request  were  made  and  that  no  widgets  should  actually  be 
changed. 

XtMakeGeometryRequest,  like  the  Xlib  XConf  igureWindow  function,  uses 
request_mode  to  determine  which  fields  in  the  XtWidgetGeometry  structure  you  want 
to  specify. 

The  stack_mode  definitions  are  from  <XlllX.h>\ 

o 
i 

2 
3 

4 

,-' 

The  Intrinsics  also  support  the  following  value: 

#define         XtSMDontChange        5 

For  precise  definitions  of  Above,  Below,  Toplf ,  Bottomlf ,  and  Opposite,  see  the  refer 
ence  page  for  XConf  igureWindow  in  Volume  Two,  Xlib  Reference  Manual.  XtSMDont 
Change  indicates  that  the  widget  wants  its  current  stacking  order  preserved. 

See  Also 

XtMakeGeometryRequest  (1 ), 
Composite(3),  Core(3). 


#define 

Above 

#define 

Below 

#define 

Toplf 

#def  ine 

Bottomlf 

#def  ine 

Opposite 
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J  XtRealizeWidget 


Name 

XtRealizeWidget  —  realize  a  widget  instance. 

Synopsis 

void  XtRealizeWidget (w) 
Widget  w, 

Arguments 

w  Specifies  the  widget  to  be  realized. 

Description 

XtRealizeWidget  causes  widgets  to  set  window  attributes,  create  their  windows  on  the  dis 
play,  and  perform  their  final  initializations.  XtRealizeWidget  is  called  just  prior  to  calling 
XtAppMainLoop  to  process  events.  The  argument  to  XtRealizeWidget  is  usually  the 
top-level  widget  returned  from  xtApplnitialize. 

If  the  widget  is  already  realized,  XtRealizeWidget  simply  returns.  Otherwise,  it  performs 
the  following: 

•  Binds  all  action  names  in  the  widget's  translation  table  to  procedures. 

•  Makes  a  post-order  traversal  of  the  widget  tree  rooted  at  the  specified  widget  and  calls 
the  change_managed  method  of  each  composite  widget  that  has  one  or  more  managed 
children. 

•  Constructs  an  XSetwindowAttributes  structure  filled  in  with  information  derived 
from  the  Core  widget  fields  and  calls  the  realize  method  for  the  widget,  which  adds 
any  widget-specific  attributes  and  creates  the  X  window. 

•  If  the  widget  is  not  a  subclass  of  compositeWidgetClass,  XtRealizeWidget 
returns;  otherwise,  it  performs  the  following: 

Descends  recursively  to  each  of  the  widget's  managed  children  and  calls  the  real 
ize  procedures.  Primitive  widgets  that  instantiate  children  are  responsible  for  real 
izing  those  children  themselves. 

Maps  all  of  the  managed  child  windows  that  have  mapped_when_managed 
True.  (If  a  widget  is  managed  but  mapped_when_managed  is  False,  the 
widget  is  allocated  visual  space  but  is  not  displayed.) 

If  the  widget  is  a  top-level  shell  widget  (that  is,  if  it  has  no  parent)  and 
mapped_when_managed  is  True,  then  XtRealizeWidget  maps  the  widget  window. 

XtCreateWidget,  XtRealizeWidget,  XtManageChildren,  XtUnmanage- 
Children,  and  XtDestroyWidget  maintain  the  following  invariants: 
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•  If  a  widget  is  realized,  then  all  of  its  managed  children  are  realized. 

•  If    a    widget    is    realized,    then    all    of    its    managed    children    that    are    also 
mapped_when_managed  are  mapped. 

All  Intrinsics  functions  and  all  widget  methods  should  accept  either  realized  or  unrealized 
widgets.  When  calling  the  realize  methods  for  children  of  a  composite  widget,  xt- 
RealizeWidget  calls  the  methods  in  reverse  order  of  appearance  in  the  list  specified  by 
composite. children.  By  default,  this  causes  the  stacking  order  of  any  newly  created 
subwindows  to  be  top-to-bottom  in  the  order  of  appearance  on  the  list,  with  the  most  recently 
created  child  at  the  bottom. 

See  Also 

AppXtInUialize(l\  XtIsRealized(l),  XtUnrealizeWidget(l\ 

Core(3), 

realize(4). 
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-X.-MemoryAHoca..,.,, XtReall°C 

Name 

XtRealloc  —  change  the  size  of  an  allocated  block  of  storage. 

Synopsis 

char  *XtRealloc (ptr,  num) ; 
char  *ptr; 
unsigned  int  num; 

Arguments 

ptr  Specifies  a  pointer  to  the  old  storage. 

num  Specifies  the  number  of  bytes  desired  in  total  storage. 

Description 

XtRealloc  changes  the  size  of  a  block  of  storage,  possibly  moving  it  Then,  it  copies  the  old 
contents  (or  as  much  as  will  fit)  into  the  new  block  and  frees  the  old  block.  If  there  is  insuffi 
cient  memory  to  allocate  the  new  block,  XtRealloc  terminates  by  calling  xtErrorMsg. 

If  ptr  is  NULL,  XtRealloc  allocates  the  new  storage  without  copying  the  old  contents.  That 
is,  it  simply  calls  XtMalloc. 

The  function  XtRealloc  is  implemented  by  the  Toolkit  independently  of  the  particular  envi 
ronment,  so  programs  ported  to  a  system  not  supporting  realloc  will  still  work. 

See  Also 

XtAlIocd),  XtErrorMsg(l\  XtFree(\\  XtMalloc(\\  XtNew(l),  XtNewString(l). 
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XtRegisterCaseConverter  \ 

v Xt-  Keyboard  Handling  — 

Name 

XtRegisterCaseConverter  —  register  a  case  converter. 

Synopsis 

void  XtRegisterCaseConverter (display,  proc,  start,  stop) 
Display  *  display; 
XtCaseProc  proc; 
KeySym  start; 
KeySym  stop; 

Arguments 

display  Specifies  the  display  from  which  the  key  events  are  to  come. 

proc  Specifies  the  XtCaseProc  that  is  to  do  the  conversions. 

start  Specifies  the  first  keysym  for  which  this  converter  is  valid. 

stop  Specifies  the  last  keysym  for  which  this  converter  is  valid. 

Description 

XtRegisterCaseConverter  registers  the  specified  case  converter  (see  XtCase- 
Proc(2)).  start  and  stop  provide  the  inclusive  range  of  keysyms  for  which  this  converter 
is  to  be  called.  The  new  converter  overrides  any  previous  converters  for  keysyms  in  that  range. 

The  only  way  to  remove  a  converter  is  to  register  a  new  one.  For  example,  the  default  key 
translator  (_xtConvertCase)  can  be  explicitly  reinstalled.  The  default  converter  under 
stands  case  conversion  for  all  keysyms  defined  in  the  XI 1  protocol.  The  keysyms  defining  a 
keysym  range  are  defined  in  <Xlllkeysym.h>. 

The  various  functions  for  remapping  the  keyboard  are  discussed  in  Chapter  13,  Miscellaneous 
Toolkit  Programming  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 

Structures 

typedef  XID  KeySym; 

See  Also 

XtConvertCase(\\  XtGetKeysymTable(l),  XtKeysymToKeycodeList(\\  XtSetKeyTranslator(\\  Xt- 
TranslateKeycode  ( 1 ), 
XtCaseProc (2),  XtKeyProc(2). 
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.  XtRegisterGrabAction 

— Xt  -  Translations  and  Actions ' 

Name 

XtRegisterGrabAction  —  register  button  and  key  grabs  for  a  widget's  window  according  to  the 
event  bindings  in  the  widget's  translation  table. 

Synopsis 

void  XtRegisterGrabAction  (action_proc,  ovrner_events,  event_mask, 

pointer_mode,  keyboard_mode) 
XtActionProc  action_proc; 
Boolean  owner_events; 
unsigned  int  event_mask; 
int  pointer_mode,  keyboard_mode; 

Arguments 

actionjproc      Specifies  the  action  procedure  to  search  for  in  the  translation  table(s). 

owner_events    Specifies  a  Boolean  value  of  either  True  or  False.  See  Description  below. 

even t_mask  Specifies  the  event  mask  to  take  effect  during  the  grab.  This  mask  is  the  bit 
wise  OR  of  one  or  more  of  the  event  masks  listed  on  the  reference  page  for 
XSelectlnput. 

pointer_mode  Controls  processing  of  pointer  events  during  the  grab.  Pass  one  of  these  con 
stants:  GrabModeSync  or GrabModeAsync. 

keyboard_mode  Controls  processing  of  keyboard  events  during  the  grab.  Pass  one  of  these 
constants:  GrabModeSync  or  GrabModeAsync. 

Description 

To  register  button  and  key  grabs  for  a  widget's  window  according  to  the  event  bindings  in  the 
widget's  translation  table,  use  XtRegisterGrabAction. 

XtRegisterGrabAction  adds  the  specified  action_proc  to  a  list  known  to  the  transla 
tion  manager.  When  a  widget  is  realized,  or  when  the  translations  of  a  realized  widget  or  the 
accelerators  installed  on  a  realized  widget  are  modified,  its  translation  table  and  any  installed 
accelerators  are  scanned  for  action  procs  on  this  list. 

If  any  are  invoked  on  Button? res s  or  KeyPress  events  as  the  only  or  final  event  in  a 
sequence,  the  Intrinsics  will  call  xtGrabButton  or  XtGrabKey  for  the  widget  with  every 
button  or  keycode  that  maps  to  the  event  detail  field,  passing  the  specified  owner_events, 
event_mask,pointer_mode,  and  keyboard_mode. 

•      For  ButtonPress  events,  the  modifiers  specified  in  the  grab  are  determined  directly 
from  the  translation  specification,  and  confine_to  and  cursor  are  specified  as  None. 
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For  Key P  r  e  s  s  events: 

—  If  the  translation  table  entry  specifies  colon  (:)  in  the  modifier  list,  the  modifiers  are 
determined  by  calling  the  key  translator  procedure  registered  for  the  display  and  by 
calling  xtGrabKey  for  every  combination  of  standard  modifiers  that  map  the  key- 
code  to  the  specified  event  detail  keysym,  and  ORing  any  modifiers  specified  in  the 
translation  table  entry,  and  event_mask  is  ignored. 

—  If  the  translation  table  entry  does  not  specify  colon  in  the  modifier  list,  the  modifiers 
specified  in  the  grab  are  those  specified  in  the  translation  table  entry  only. 

For  both  ButtonPress  and  KeyPress  events,  "don't  care  modifiers"  are  ignored  unless  the 
translation  entry  explicitly  specifies  "Any"  in  the  modifiers  field. 

If  the  specified  action_proc  is  already  registered  for  the  calling  process,  the  new  values 
replace  the  previously  specified  values  for  any  widgets  that  are  realized  following  the  call,  but 
existing  grabs  are  not  altered. 

When  translations  or  installed  accelerators  are  modified  for  a  realized  widget,  any  previous  key 
or  button  grabs  that  were  registered  as  a  result  of  the  old  bindings  are  released,  provided  that 
the  old  bindings  do  not  appear  in  the  new  bindings  and  are  not  explicitly  grabbed  by  the  client 
with  XtGrabKey  orXtGrabButton. 

See  Also 

XtAddActions(\),  XtAppAddActionHook(\),  XtAppAddActions(\\  XtCaIlActionProc(l),  XtGetAction- 
Keysym(l),  XtRemoveActionHook(\). 
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Name 

XtReleaseGC  —  deallocate  a  shared  GC  when  it  is  no  longer  needed. 

Synopsis 

void  XtReleaseGC  (object,  gc) 
Widget  object; 
GC  gc; 


Arguments 

object 

gc 


Specifies  any  object  on  the  display  for  which  the  GC  was  created;  may  be  of 
class  Object  or  any  subclass  thereof. 

Specifies  the  GC  to  be  deallocated. 


Description 

XtReleaseGC  disassociates  an  application  from  a  GC  allocated  with  xtGetGC.  Xt 
ReleaseGC  supersedes  xtDestroyGC  and  must  be  used  instead  of  xtDestroyGC  if  the 
application  is  using  XtGetGC  on  multiple  displays. 

The  Intrinsics  maintain  reference  counts  of  sharable  GCs  allocated  by  XtGetGC.  The  Intrin- 
sics  do  not  actually  pass  a  free  request  to  the  server  until  the  last  user  of  a  GC  in  an  application 
releases  it 

The  Intrinsics  use  a  caching  mechanism  for  sharable  read-only  GCs.  This  is  explained  in  Chap 
ter  6,  Basic  Widget  Methods,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 

See  Also 

XtDestroyGC  '(1),  XtGetGC(l\ 
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XtRemoveActionHook 

•Xt  -  Translations  and  Actions- 
Name 

XtRemoveActionHook  —  unregister  an  action  hook  procedure. 

Synopsis 

void  XtRemoveActionHook (id) 
XtActionHookld  id; 

Arguments 

id  Specifies  the  action  hook  ID  returned  by  xtAppAddActionHook. 

Description 

XtRemoveActionHook  removes  the  specified  action  hook  procedure  from  the  application 
context  in  which  it  was  registered. 

See  Also 

XtAddActlonHook(\\ 
XtActionHookProc  (2). 
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„  1IU  ,     J  XtRemoveAIICallbacks 

— Xt  -  Callbacks ' 

Name 

XtRemoveAIICallbacks  —  delete  all  procedures  from  a  callback  list. 

Synopsis 

void  XtRemoveAIICallbacks (object,  callback_name) 
Widget  object; 
String  callback_name; 

Arguments 

object  Specifies  the  object  whose  callbacks  are  to  be  deleted;  may  be  of  class 

Object  or  any  subclass  thereof. 

ca l lback_name       Specifies  the  callback  list  to  be  removed. 

Description 

XtRemoveAIICallbacks  removes  all  the  widget's  callback  procedures  identified  by 
callback_name,  regardless  of  the  value  of  the  client_data  associated  with  each  proce 
dure.  This  is  in  contrast  to  xtRemoveCallback  and  xtRemoveCallbacks,  which 
remove  the  specified  callback  only  if  a  specified  client_data  argument  also  matches. 

Calling  any  of  these  routines  implicitly  frees  storage  associated  with  the  Intrinsics'  internal 
representation  of  the  callback  list. 

See  Also 

XtAddCollbacks(\),  XtCallCallbacks(\\  XtRemoveCallback(l\  XtRemoveCallbacks(\). 
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XtRemoveCallback  \ 


•Xt-  Callbacks- 


Name 

XtRemoveCallback  —  delete  a  procedure  from  a  callback  list. 

Synopsis 

void  XtRemoveCallback (object,  callback_name,  callback,  client_data) 
Widget  object; 
String  callback_name; 
XtCallbackProc  callback; 
XtPointer  client_data; 

Arguments 

object  Specifies  the  object;  may  be  of  class  Object  or  any  subclass  thereof. 

callback_name  Specifies  the  callback  list  from  which  the  procedure  is  to  be  deleted. 

callback  Specifies  the  callback  procedure  which  is  to  be  deleted. 

client_data      Specifies  the  client  data  to  match  with  the  registered  callback  procedure. 

Description 

XtRemoveCallback  removes  a  callback  procedure  identified  by  callback_name. 

The  procedure  is  removed  only  if  both  the  procedure  callback  and  client_data  match  a 
function/data  pair  on  the  list.  No  warning  message  is  generated  if  a  procedure  to  be  removed 
fails  to  match  a  callback  or  client_data  on  the  list.  Use  XtRemoveAllCallbacks  if 
you  want  to  remove  a  particular  callback  regardless  of  the  value  of  its  client_da  t  a. 

See  Also 

XtAddCollbacks(\\  XtCollCallbacks(\\  XtRemoveAllCallbacks (1),  XtRemoveCallbacks(\). 
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-x«  -  ca,,backs /  XtRemoveCallbacks 

Name 

XtRemoveCallbacks  —  delete  a  list  of  procedures  from  a  callback  list. 

Synopsis 

void  XtRemoveCallbacks (object,  callback_name,  callbacks) 
Widget  object; 
String  callback_name; 
XtCallbackList  callbacks; 

Arguments 

object  Specifies  the  object;  may  be  of  class  Object  or  any  subclass  thereof. 

callback_name  Specifies  the  callback  list  from  which  the  procedure  is  to  be  deleted. 

callbacks         Specifies  the  NULL-terminated  list  of  callback  procedures  and  corresponding 
client  data  to  be  deleted. 

Description 

XtRemoveCallbacks  removes  a  list  of  procedures  from  the  callback  list  identified  by  the 
resource  callback_name. 

The  procedure  is  removed  only  if  both  the  procedure  callback  and  client_data  match  a 
function/data  pair  on  the  list.  No  warning  message  is  generated  if  a  procedure  to  be  removed 
fails  to  match  a  callback  on  the  list.  Use  XtRemoveAllCallbacks  if  you  want  to  remove  a 
particular  callback  regardless  of  the  value  of  its  client_data. 

Structures 

typedef  struct  _XtCallbackRec*   XtCallbackList; 

See  Also 

XtAddCcdlbacks(\\  XtCallCallbacks(l\  XtRemoveAllCallbacks(\\  XtRemoveCallback(\). 
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XtRemoveEventHandler  A 

v Xt  -  Event  Handling  — 

Name 

XtRemoveEventHandler  —  remove  a  previously  registered  event  handler. 

Synopsis 

void  XtRemoveEventHandler (w,  event_mask,  nonmaskable,  proc, 

client_data) 
Widget  w; 

EventMask  event_mask; 
Boolean  nonmaskable; 
XtEventHandler  proc; 
XtPointer  client_data; 

Arguments 

w  Specifies  the  widget  for  which  this  handler  is  registered. 

event_mask        Specifies  the  events  for  which  to  unregister  this  handler. 

nonmaskable  Specifies  a  Boolean  value  that  indicates  whether  this  handler  should  be  unre 
gistered  for  nonmaskable  events  (GraphicsExpose,  NoExpose, 
SelectionClear,  SelectionRequest,  SelectionNotify, 
ClientMessage,  and  MappingNotif y ) . 

proc  Specifies  the  handler  procedure  to  be  removed. 

cllent_data      Specifies  the  client  data  to  match  on  the  registered  handler. 

Description 

XtRemoveEventHandler  stops  the  specified  procedure  from  being  called  in  response  to  the 
specified  events. 

A  handler  is  removed  only  if  both  the  procedure  proc  and  client_data  match  a  previously 
registered  handler/data  pair.  If  a  handler  to  be  removed  fails  to  match  a  procedure,  or  if  it  has 
been  registered  with  a  different  value  of  client_data,  XtRemoveEventHandler  returns 
without  reporting  an  error. 

If  the  widget  is  realized,  XtRemoveEventHandler  calls  XSelectlnput,  if  necessary,  to 
prevent  the  client  from  receiving  further  events  of  that  type. 

To  keep  an  event  handler  from  being  called  at  all,  call  XtRemoveEventHandler  with  an 
event_mask  of  XtAllEvents  with  nonmaskable  True,  and  the  client_data  registered 
in  a  previous  call  to  xtAddEventHandler. 

Structures 

The  event_mask  is  formed  by  combining  the  event  mask  symbols  listed  in  the  first  column  of 
the  table  below  using  the  bitwise  OR  operator  (|).  Each  mask  symbol  sets  a  bit  in  the 
even  t_mask. 

The  table  also  describes  briefly  the  circumstances  under  which  you  would  want  to  specify  each 
symbol. 
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(continued) 


XtRemoveEventHandler 


Event  Mask  Symbol 


Circumstances 


NoEventMask 

KeyPressMask 

KeyReleaseMask 

ButtonPressMask 

ButtonReleaseMask 

EnterWindowMask 

LeaveWindowMask 

Point erMotionMask 

Point erMotionHintMask 

ButtonlMotionMask 

Button2MotionMask 

ButtonSMotionMask 

ButtonlMotionMask 

ButtonSMotionMask 

ButtonMotionMask 

KeymapStateMask 

ExposureMask 

VisibilityChangeMask 

StructureNotifyMask 

ResizeRedirectMask 

SubstructureNotifyMask 

SubstructureRedirectMask 

FocusChangeMask 

PropertyChangeMask 

ColormapChangeMask 

Owner GrabButtonMask 


No  events 

Keyboard  down  events 

Keyboard  up  events 

Pointer  button  down  events 

Pointer  button  up  events 

Pointer  window  entry  events 

Pointer  window  leave  events 

All  pointer  motion  events 

Fewer  pointer  motion  events 

Pointer  motion  while  button  1  down 

Pointer  motion  while  button  2  down 

Pointer  motion  while  button  3  down 

Pointer  motion  while  button  4  down 

Pointer  motion  while  button  5  down 

Pointer  motion  while  any  button  down 

Any  keyboard  state  change  on  EnterNotif  y, 

LeaveNotif  y,  Focusln  or  FocusOut 

Any  exposure  (except  GraphicsExpose  and 

NoExpose) 

Any  change  in  visibility 

Any  change  in  window  configuration. 

Redirect  resize  of  this  window 

Notify  about  reconfiguration  of  children 

Redirect  reconfiguration  of  children 

Any  change  in  keyboard  focus 

Any  change  in  property 

Any  change  in  colormap 

Modifies  handling  of  pointer  events 


See  Appendix  C,  Event  Reference,  for  more  information  on  event  types  and  masks. 
See  Also 

XtAddEventHandler(l),  XtRemoveRawEventHandter(l ), 
XtEventHandler(2). 
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XtRemoveGrab  \ V| 

v Xt  -  Pop  Ups— 

Name 

XtRemoveGrab  —  redirect  user  input  from  modal  widget  back  to  normal  destination. 

Synopsis 

void  XtRemoveGrab ( w) 
Widget    w; 

Arguments 

w  Specifies  the  widget  to  remove  from  the  modal  cascade.  XtRemoveGrab 

does  not  terminate  a  grab  requested  through  the  server;  it  simply  changes  Xt's 
event  dispatching. 

Description 

XtRemoveGrab  removes  widgets  from  the  modal  cascade  (a  set  of  widgets  that  lock  out  user 
input  to  the  application  except  through  themselves).  It  issues  a  warning  if  the  specified  widget 
is  not  in  the  modal  cascade. 

The  modal  cascade  is  a  data  structure  used  by  xtDispatchEvent  when  it  tries  to  dispatch  a 
user  event  It  is  a  list  of  widgets  which  have  issued  a  request,  from  the  Intrinsics,  for  events 
that  would  ordinarily  be  outside  their  jurisdiction. 

When  the  modal  cascade  is  not  empty,  XtDispatchEvent  delivers  the  event  to  the  most 
recent  modal  cascade  entry,  with  the  exclusive  parameter  True. 

Both  XtPopup  and  XtPopupSpringLoaded  use  XtAddGrab  and  XtRemoveGrab  to 
constrain  user  events  to  a  modal  cascade.  It  is  unusual  to  call  XtAddGrab  or  XtRemove 
Grab  explicitly. 

See  Also 

XtAddGrab(\\  XtDispaichEvent(\\  XtPopup(l),  XtPopupSpringLoaded(l). 
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J  XtRemovelnput 


Name 

XtRemovelnput  —  unregister  a  file  procedure,  a  pipe  procedure,  or  a  socket  procedure. 

Synopsis 

void  XtRemovelnput (id) 
Xt Input Id  id; 

Arguments 

id  Specifies  the  ID  returned  from  the  corresponding  xtAppAddlnput  call. 

Description 

XtRemovelnput  causes  the  Intrinsics  to  stop  watching  for  events  from  an  alternate  input 
source  registered  with  XtAppAddlnput.  Alternate  input  events  are  usually  operating  system 
reads,  but  they  can  be  any  I/O  operation  supported  by  the  operating  system. 

For  more  general  discussion  of  alternate  input  events,  see  Chapter  8,  More  Input  Techniques, 
in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 

See  Also 

XtAddInput(l),  XtAppAddInput(\\ 
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XtRemoveRawEventHandler 

Xt  -  Event  Handling  — 

Name 

XtRemoveRawEventHandler  —  remove  a  raw  event  handler. 

Synopsis 

void  XtRemoveRawEventHandler (w,  event_mask,  nonmaskable,  proc,  client_data) 
Widget  w; 

EventMask  event_mask; 
Boolean  nonmaskable; 
XtEventHandler  proc; 
XtPointer  client_data; 

Arguments 

w  Specifies  the  widget  for  which  this  handler  is  registered. 

event_mask        Specifies  the  events  for  which  to  unregister  this  handler. 

nonmaskable  Specifies  a  Boolean  value  that  indicates  whether  this  procedure  should  be 
unregistered  for  the  nonmaskable  events  (GraphicsExpose,  NoExpose, 
SelectionClear,  SelectionRequest,  SelectionNotify, 
ClientMessage,  and  MappingNotif  y ) . 

proc  Specifies  the  procedure  to  be  matched. 

cl i en t_data      Specifies  the  client  data  to  be  matched. 

Description 

XtRemoveRawEventHandler  stops  the  specified  procedure  from  being  called  in  response 
to  the  specified  events. 

A  handler  is  removed  only  if  both  the  procedure  proc  and  client_data  match  a  previously 
registered  handler/data  pair.  If  a  handler  to  be  removed  fails  to  match  a  procedure,  or  if  it  has 
been  registered  with  a  different  value  of  client_data,  xtRemoveEventHandler  returns 
without  reporting  an  error. 

Because  the  procedure  is  a  raw  event  handler,  it  does  not  affect  the  widget's  event  mask  and 
never  calls  the  Xlib  XSelectlnput  function. 

Structures 

The  event_mask  is  formed  by  combining  the  event  mask  symbols  listed  in  the  first  column  of 
the  table  below  using  the  bitwise  OR  operator  (|).  Each  mask  symbol  sets  a  bit  in  the 
event_mask. 

The  table  also  describes  briefly  the  circumstances  under  which  you  would  want  to  specify  each 
symbol. 
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(continued) 


XtRemoveRawEventHandler 


Event  Mask  Symbol 


Circumstances 


NoEventMask 

KeyPressMask 

KeyReleaseMask 

ButtonPressMask 

ButtonReleaseMask 

EnterWindowMask 

LeaveWindowMask 

PointerMotionMask 

Point erMotionHintMask 

ButtonlMotionMask 

Button2MotionMask 

ButtonSMotionMask 

Button4MotionMask 

ButtonSMotionMask 

ButtonMotionMask 

KeymapStateMask 

ExposureMask 

VisibilityChangeMask 
Struct ureNotifyMask 
ResizeRedirectMask 
Subs truct ureNotifyMask 
Subs t rue tureRedirect Mask 
FocusChangeMask 
PropertyChangeMask 
ColormapChangeMask 
Owner GrabButtonMask 


No  events 

Keyboard  down  events 

Keyboard  up  events 

Pointer  button  down  events 

Pointer  button  up  events 

Pointer  window  entry  events 

Pointer  window  leave  events 

All  pointer  motion  events 

Fewer  pointer  motion  events 

Pointer  motion  while  button  1  down 

Pointer  motion  while  button  2  down 

Pointer  motion  while  button  3  down 

Pointer  motion  while  button  4  down 

Pointer  motion  while  button  5  down 

Pointer  motion  while  any  button  down 

Any  keyboard  state  change  on  EnterNotif  y, 

LeaveNotify,  Focusln  or  FocusOut 

Any  exposure  (except  GraphicsExpose  and 

NoExpose) 

Any  change  in  visibility 

Any  change  in  window  configuration. 

Redirect  resize  of  this  window 

Notify  about  reconfiguration  of  children 

Redirect  reconfiguration  of  children 

Any  change  in  keyboard  focus 

Any  change  in  property 

Any  change  in  colormap 

Modifies  handling  of  pointer  events 


See  Appendix  C,  Event  Reference,  for  more  information  on  event  types  and  masks. 
See  Also 

XtRemoveEventHandler  ( 1 ), 
XtEventHandler(2\ 
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XtRemoveTimeOut  A 

v Xt  -  Event  Handling— 

Name 

XtRemoveTimeOut  —  unregister  a  timeout  procedure. 

Synopsis 

void  XtRemoveTimeOut (id) 
Xtlntervalld  id; 

Arguments 

i  d  Specifies  the  ID  for  the  timeout  registration  to  be  destroyed. 

Description 

XtRemoveTimeOut  removes  the  timeout  specified  by  id.  id  is  the  value  returned  by  either 

XtAppAddTimeOut  orXtAddTimeOut. 

Note  that  timeouts  are  automatically  removed  once  they  expire  and  the  callback  has  been 
called. 

For  an  example  and  discussion  of  timeouts,  see  Chapter  8,  More  Input  Techniques,  in  Volume 
Four,  X  Toolkit  Intrinsics  Programming  Manual. 

See  Also 

XtAddTimeOut(\\  XtAppAddTimeOut(\\ 
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E    .u    .„   J  XtRemoveWorkProc 

— Xt  -  Event  Handling * 

Name 

XtRemoveWorkProc  —  unregister  a  work  procedure. 

Synopsis 

void  XtRemoveWorkProc (id) 
XtWorkProdd  id; 

Arguments 

i  d  Specifies  which  work  procedure  to  unregister. 

Description 

XtRemoveWorkProc  explicitly  removes  the  specified  background  work  procedure.  The  xt- 
WorkProcld  is  returned  from  a  corresponding  xtAppAddWorkProc  call. 

An  xtWorkProc  is  removed  automatically  once  it  returns  True. 
See  Also 

XtAddWorkProc(\),  XtAppAddWorkProc(\\ 
XtWorkProc  (2). 
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XtResizeWidget 

— Xt  -  Geometry  Management- 
Name 

XtResizeWidget  —  resize  a  child  or  sibling  widget 

Synopsis 

void   XtResizeWidget  (w,    width,    height,    border_width) 
Widget    w; 
Dimension    width; 
Dimension   height; 
Dimension   bar der_ width ; 

Arguments 

w  Specifies  the  widget  to  be  resized. 

width,  height,  border_width 

Specify  the  new  widget  size  and  border  width. 

Description 

XtResizeWidget  is  customarily  used  by  a  parent  to  resize  its  children. 

XtResizeWidget  returns  immediately  if  the  specified  geometry  fields  are  the  same  as  the 
old  values.  Otherwise,  XtResizeWidget  writes  the  new  width,  height,  and 
border_\ffidth  values  into  the  widget  and,  if  the  widget  is  realized,  issues  an  Xlib 
XConf  igureWindow  call  on  the  widget's  window. 

XtResizeWidget  calls  the  specified  widget's  resize  method  to  notify  it  of  the  size 
change.  The  resize  method  allows  the  widget  to  lay  out  its  displayed  data  to  match  the  new 
size.  If  a  class  need  not  recalculate  anything  when  it  is  resized,  it  can  specify  NULL  for  the 
resize  field  in  its  class  record.  This  is  an  unusual  case  and  should  occur  only  for  widgets 
with  trivial  display  semantics.  The  resize  method  takes  a  widget  as  its  only  argument. 

See  Also 

XtConfigureWidget(l),  XtMakeGeometryRequest(l),  XtQueryGeometry(\),  XtResizeWindow(\), 
resize^). 
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„„  .    „  /  XtResizeWindow 

— Xt-  Window  Manipulation ' 

Name 

XtResizeWindow  —  resize  a  widget  according  to  its  core  dimensions. 

Synopsis 

void  XtResizeWindow (w) 
Widget  w; 

Arguments 

w  Specifies  the  widget. 

Description 

XtResizeWindow  calls  the  XConf  igureWindow  Xlib  function  to  make  the  window  of  the 
specified  widget  match  its  Core  width,  height,  and  border_width. 

The  call  to  XConf  igureWindow  is  done  unconditionally  because  there  is  no  way  to  tell 
(without  a  server  query)  whether  these  values  match  the  current  values. 

XtResizeWindow  does  not  cause  the  widget's  resize  method  to  be  called. 

You  rarely  need  to  use  XtResizeWindow;  it  is  more  diplomatic  to  use  xtResizeWidget. 

See  Also 

XtResizeWidgetd) 
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XtResolvePathname  A 

Xt  -  File  Searching— 

Name 

XtResolvePathname  —  search  for  a  file  using  standard  substitutions  in  a  path  list. 

Synopsis 

String  XtResolvePathname (display,  type,  filename,  suffix,  path,  substitu 
tions,  num_substi  tut  ions,  predicate) 
Display  *  display; 

String  type,  filename,  suffix,  path; 
Substitution  substitutions; 
Cardinal  num_substi tut  ions; 
XtFilePredicate  predicate; 

Arguments 

display  Specifies  the  display  to  use  to  find  the  language  for  language  substitutions. 

type 

filename 

suffix  Specify  values  to  substitute  into  the  path. 

pa  th  Specifies  the  list  of  file  specifications,  or  NULL. 

substitutions  Specifies  a  list  of  additional  substitutions  to  make  into  the  path,  or  NULL. 

num_substi tut  ions 

Specifies  the  number  of  entries  in  substitutions. 

predi  cate         Specifies  a  procedure  called  to  judge  each  potential  file  name,  or  NULL. 

Description 

The  Intrinsics  provide  two  routines  to  look  for  a  file  by  name  using  string  substitutions  in  a  list 
of  file  specifications.  xtFindFile  uses  an  arbitrary  set  of  client-specified  substitutions, 
whereas  XtResolvePathname  uses  a  set  of  standard  substitutions  corresponding  to  the 
X/Open  Portability  Guide  language  localization  conventions.  Most  applications  should  use 
XtResolvePathname,  which  calls  XtFindFile. 

The  substitutions  specified  by  XtResolvePathname  are  determines  from  the  value  of  the 
language  string  retrieved  by  xtDisplaylnitialize  for  the  specified  display.  A  language 
is  specified  from  three  parts,  two  of  which  are  optional:  the  language,  the  territory,  and  the 
codeset.  These  parts  are  combined  into  a  single  string  as  follows: 

language [_territory] [.codeset] 

The  parts  consist  of  arbitrary  strings  of  letters  and  numbers.  The  parts  of  the  language  are  not 
interpreted  except  when  used  in  substitutions.  To  set  the  language  for  all  applications  specify: 

*xnlLanguage :    lang 
in  the  resource  database. 

XtResolvePathname  calls  XtFindFile  with  the  following  substitutions  in  addition  to 
any  passed  by  the  caller  and  returns  the  value  returned  by  XtFindFile: 
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%N  The  value  of  the  filename  parameter,  or  the  application's  class  name  if  filename  is  NULL. 

%T  The  value  of  the  type  parameter. 

%S  The  value  of  the  suffix  parameter. 

%L  The  language  specification  associated  with  the  specified  display. 

%1  The  language  part  of  the  display's  language  spec. 

%t  The  territory  part  of  the  display's  language  spec. 

%c  The  codeset  part  of  the  display's  language  spec. 

If  a  path  is  passed  to  XtResoivePathname  it  will  be  passed  along  to  xtFindFile.  If  path 
is  NULL,  the  value  of  the  XFILESEARCHPATH  environment  variable  will  be  passed  to  Xt 
FindFile.  If  XFILESEARCHPATH  is  not  defined,  an  implementation-specific  default  path 
will  be  passed  in  which  contains  at  least  /usr/lib/XM/%T/%N%S.  If  the  path  begins  with  a 
colon,  it  will  be  preceded  by  %N%S.  If  the  path  includes  two  adjacent  colons,  %N%S  will  be 
inserted  between  them. 

The  type  parameter  is  intended  to  be  a  category  of  files,  usually  being  translated  into  a  direc 
tory  in  the  pathname.  Possible  values  might  include  app-defaults ,  help,  and  bitmap. 

The  suffix  parameter  is  intended  to  be  appended  to  the  file  name.  Possible  values  might  include 
.txt,  .dat,  and  .bm. 

A  suggested  value  for  the  default  path  on  POSIX-based  systems  is: 

lusrlliblXll  l%LI%TI%N%S:lusrlliblXlll%ll%TI%N%S:lusrlliblXlll%TI%N%S 

Using  this  example,  if  the  user  has  specified  a  language,  it  will  be  used  as  a  subdirectory  of 
lusrlliblXll  that  will  be  searched  for  other  files.  If  the  desired,  file  is  not  found  there,  the 
lookup  will  be  tried  again  using  just  the  language  part  of  the  specification.  If  the  file  is  not 
there  it  will  be  looked  for  in  lusrlliblXll.  The  type  parameter  is  used  as  a  subdirectory  of  the 
language  directory  or  of  lusrlliblXll ,  and  the  suffix  is  appended  to  the  file  name. 

It  is  the  responsibility  of  the  caller  to  free  the  returned  string  using  xtFree  when  it  is  no 
longer  needed. 

Structures 

A  string  substitution  is  defined  by  a  list  of  Substitution  entries. 

typedef  struct  { 

char  match; 

String  substitution; 
}  SubstitutionRec,  * Substitution ; 

See  Also 

XtFindFUe(l), 
XtFilePredicate(2). 
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A  ^ Xt  -  Object  Information  — 

Name 

XtScreen  —  return  the  screen  pointer  for  the  specified  widget 

Synopsis 

Screen  *  XtScreen  ( w) 
Widget  w; 

Arguments 

w  Specifies  the  widget 

Description 

XtScreen  returns  a  pointer  to  the  Screen  structure  that  describes  the  screen  the  specified 
widget  is  on. 

See  Also 

XtDisplay(l) 
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^Ul    ,  ,       ,   J  XtScreenOfObject 

— Xt  -  Object  Information ' 

Name 

XtScreenOfObject  —  return  the  screen  pointer  for  the  nearest  ancestor  of  object  that  is  of  class 
Core. 

Synopsis 

Screen  *XtScreenOfOb ject (object) 
Widget  object; 

Arguments 

object  Specifies  the  object;  may  be  of  class  Object  or  any  subclass  thereof. 

Description 

XtScreenOfObject  is  identical  in  function  to  XtScreen  if  the  object  is  a  widget;  other 
wise  XtScreenOfObject  returns  the  screen  pointer  for  the  nearest  ancestor  of  object  that  is 
of  class  Core. 

See  Also 

XtDisplayOJDbject(l),  XtWindowOJObject(l). 
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XtSetArg  \ ¥1 

v Xt  -  Argument  Lists- 
Name 

XtSetArg  —  modify  an  argument  list  dynamically. 

Synopsis 

void  XtSetArg (arg,  resource_name,  value) 
Arg  arg; 

String  resource_name; 
XtArgVal  value; 

Arguments 

arg  Specifies  the  Arg  structure  to  set 

resource_name  Specifies  the  name  of  the  resource. 

value  Specifies  the  value  of  the  resource,  or  its  address.  (If  the  size  of  the  resource 

is  less  than  or  equal  to  the  size  of  an  XtArgVal,  the  resource  value  is  stored 
directly  in  val  ue;  otherwise,  a  pointer  to  it  is  stored  in  val  ue.) 

Description 

Many  Intrinsics  functions  need  to  be  passed  pairs  of  resource  names  and  values  to  set  or  over 
ride  resource  values.  One  way  to  do  this  is  to  construct  and  pass  an  ArgList  (see  the  Struc 
tures  section  below).  To  dynamically  change  values  in  an  existing  Arg  or  ArgList,  use  Xt 
SetArg. 

The  (varargs  interfaces)  style  of  Intrinsics  calls  (those  that  start  with  xtVa)  avoid  the  need  to 
build  an  ArgList  or  call  XtSetArg. 

Note  that  XtSetArg  is  implemented  as  a  macro.  Expressions  involving  autoincrement  and 
autodecrement  operations  are  unsafe  in  its  argument  list,  since  XtSetArg  evaluates  its  first 
argument  twice. 

XtSetArg  is  usually  used  in  a  highly  stylized  manner  to  minimize  the  probability  of  making  a 
mistake;  for  example: 

Arg  args[20] ; 
int   n; 

n   =   0; 

XtSetArg (args [n] ,  XtNheight,  100);  n++; 
XtSetArg (args [n] ,  XtNwidth,  200);  n++; 
XtSetValues (widget,  args,  n) ; 

Alternatively,  an  application  can  statically  declare  the  argument  list  and  use  xtNumber : 

static  Args  args [ ]  =  { 

{XtNheight,  (XtArgVal)  100}, 
{XtNwidth,  (XtArgVal)  200}, 

}; 

XtSetValues (Widget,  args,  XtNumber (args) ); 
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Xt  -  Argument  Lists  (continued)  XtSetArg 

Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual,  presents  several  examples  that  use 
Args,  setting  them  in  several  ways:  with  values  initialized  at  compile  time;  by  using  xtSet- 
Arg;  and,  by  using  the  varargs  interfaces. 

Structures 

Arg  are  defined  as  follows  in  <X11 /Intrinsic. h>\ 

typedef  struct  { 

String  name; 

XtArgVal  value; 
}  Arg,  *ArgList; 

If  the  size  of  the  resource  is  less  than  or  equal  to  the  size  of  an  XtArgVal,  the  resource  value 
is  stored  directly  in  value;  otherwise,  a  pointer  to  it  is  stored  into  value. 

The  definition  of  XtArgVal  differs  depending  on  architecture — its  purpose  is  precisely  to 
make  code  portable  between  architectures  with  different  byte  sizes. 

The  macro  itself,  from  the  same  file,  is  listed  below: 

#define  XtSetArg (arg,  n,  d)  (  (arg) .name=  (n)  ,  (arg)  .value=  (XtArgVal)  (d)  ) 

See  Also 

XtMergeArgLists(\\  XtNumber(\). 
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XtSetErrorHandler  \ 

v Xt  -  Error  Handling- 
Name 

XtSetErrorHandler  —  register  a  procedure  to  be  called  on  fatal  error  conditions. 

Synopsis 

void  XtSetErrorHandler (handler) 
XtErrorHandler  handler; 

Arguments 

handler  Specifies  the  new  low-level  fatal  error  procedure,  which  should  not  return. 

Description 

XtSetErrorHandler  has  been  superseded  by  XtAppSetErrorHandler.  The  Intrinsics 
let  a  client  register  procedures  that  are  to  be  called  whenever  a  fatal  or  nonfatal  error  occurs. 
These  facilities  are  intended  for  both  error  reporting  and  logging  and  for  error  correction  or 
recovery. 

Two  levels  of  interface  are  provided: 

A  high-level  interface  that  takes  an  error  name  and  class  and  looks  the  error  up  in  an 
error  resource  database.  The  high-level  fatal  error  handler  is  invoked  by  a  call  to  xt- 
ErrorMsg  or  xtAppErrorMsg;  the  high-level  nonfatal  error  handler  is  invoked  by  a 
call  to  XtWarningMsg  or  XtAppWarningMsg.  A  new  handler  can  be  registered  by 
calling  XtSetErrorMsgHandler,  XtAppSetErrorMsgHandler,  or  XtApp- 
SetWarningMsgHandler. 

•  A  low-level  interface  that  takes  a  simple  string,  which  is  printed  out  as  the  error  message. 
The  low-level  fatal  error  handler  is  invoked  by  a  call  to  xtError  or  xtAppError;  the 
low-level  nonfatal  error  handler  is  invoked  by  a  call  to  xtWarning  or  xtApp- 
Warning.  A  new  handler  can  be  registered  by  calling  XtSetErrorHandler,  xt- 
SetWarningHandler,  XtAppSetErrorHandler,  or  XtAppSetWarning- 
Handler.  .< 

The  high-level  functions  construct  a  string  to  pass  to  the  lower-level  interface.  On  POSEX- 
based  systems,  the  error  database  is  usually  lusrlliblXlllXtErrorDB. 

To  obtain  the  error  database  (for  example,  to  merge  with  an  application  or  widget-specific  data 
base),  use  XtAppGetErrorDatabase. 

Application-context-specific  error  handling  is  not  implemented  on  many  systems.  Most  imple 
mentations  will  have  just  one  set  of  error  handlers.  If  they  are  set  for  different  application  con 
texts,  the  one  set  last  will  prevail. 

The  default  low-level  fatal  error  handler  provided  by  the  Intrinsics  is  _xtError.  On  POSDC- 
based  systems,  it  prints  the  message  to  standard  error  and  terminates  the  application.  Using 
XtAppSetErrorHandler,  you  can  replace  this  default  error  handler  with  one  of  your  own. 

Fatal  error  message  handlers  should  not  return.  If  one  does,  subsequent  Toolkit  behavior  is 
undefined. 
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(continued) 


XtSetErrorHandler 


See  Also 

XtAppSetErrorMsgHandler(l),XtAppSetWarningHandler(l\ 
XtErrorHandler(2\ 
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XtSetErrorMsgHandler  vi 

> Xt  -  Error  Handling  — 

Name 

XtSetErrorMsgHandler  —  register  a  procedure  to  be  called  on  nonfatal  error  conditions. 

Synopsis 

void  XtSetErrorMsgHandler (msg_handler) 
XtErrorMsgHandler  msg_handler; 

Arguments 

msg_handler      Specifies  the  new  high-level  fatal  error  procedure,  which  should  not  return. 

Description 

XtSetErrorMsg  has  been  superseded  by  XtAppSetErrorMsgHandler.  The  Intrinsics 
let  a  client  register  procedures  that  are  to  be  called  whenever  a  fatal  or  nonfatal  error  occurs. 
These  facilities  are  intended  for  both  error  reporting  and  logging  and  for  error  correction  or 
recovery. 

Two  levels  of  interface  are  provided: 

•  A  high-level  interface  that  takes  an  error  name  and  class  and  looks  the  error  up  in  an 
error  resource  database.   The  high-level  fatal  error  handler  is  invoked  by  a  call  to  xt- 
ErrorMsg  or  xtAppErrorMsg;  the  high-level  nonfatal  error  handler  is  invoked  by  a 
call  to  XtWarningMsg  or  XtAppWarningMsg.  A  new  handler  can  be  registered  by 
calling    XtSetErrorMsgHandler,   XtAppSetErrorHandler,   or  XtAppSet- 
WarningHandler. 

•  A  low-level  interface  that  takes  a  simple  string,  which  is  printed  out  as  the  error  message. 
The  low-level  fatal  error  handler  is  invoked  by  a  call  to  xtError  or  xtAppError;  the 
low-level  nonfatal  error  handler  is  invoked  by  a  call  to  xtWarning  or  xtApp- 
Warning.  A  new  handler  can  be  registered  by  calling  xtSetErrorHandler,  xt- 
SetWarningHandler,     XtAppSetErrorHandler,     or     XtAppSetWarning- 
Handler.  -.< 

The  high-level  functions  construct  a  string  to  pass  to  the  lower  level  interface.  On  POSEX-based 
systems,  the  error  database  is  usually  lusrlliblXUIXtErrorDB. 

To  obtain  the  error  database  (for  example,  to  merge  with  an  application  or  widget-specific  data 
base),  use  XtAppGetErrorDat abase. 

Application-context-specific  error  handling  is  not  implemented  on  many  systems.  Most  imple 
mentations  will  have  just  one  set  of  error  handlers.  If  they  are  set  for  different  application  con 
texts,  the  one  set  last  will  prevail. 

The  default  error  handler  provided  by  the  Intrinsics  constructs  a  string  from  the  error  resource 
database  and  calls  XtAppError.  Using  XtAppSetErrorMsgHandler,  you  can  replace 
this  with  your  own  handler. 

See  Also 

XtAppSetErrorHandler  ( 1 ),  XtAppSetWarningMsgHandler  ( 1 ), 
XtErrorMsgHandler  (2). 
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j  XtSetKeyboardFocus 

— Xt  -  Keyboard  Handling ' 

Name 

XtSetKeyboardFocus  —  redirect  keyboard  input  to  a  normal  descendant  of  a  child  widget. 

Synopsis 

void  XtSetKeyboardFocus (subtree,  descendant) 
Widget  subtree,  descendant; 

Arguments 

subtree  Specifies  the  widget  to  be  considered  the  root  of  the  subtree  for  which  the 

keyboard  focus  is  to  be  set  (For  example,  a  composite  widget  that  is  turning 
over  all  keyboard  input  to  one  of  its  children.) 

descendant  Specifies  either  the  normal  (non-pop-up)  descendant  of  subtree  to  which 
keyboard  events  are  logically  directed,  or  None.  Note  that  it  is  not  an  error 
to  specify  None  when  no  keyboard  focus  was  previously  set. 

Description 

XtSetKeyboardFocus  causes  XtDispatchEvent  to  remap  keyboard  events  that  occur 
within  subtree  and  to  dispatch  them  to  the  specified  descendant  widget  or  to  an  ancestor.  If 
descendant  is  not  a  subclass  of  Core,  it  is  replaced  by  its  closest  windowed  ancestor.  (This 
routine  should  be  used  instead  of  calling  the  Xlib  XSetlnputFocus  routine  whenever  pos 
sible.) 

When  there  is  no  modal  cascade,  keyboard  events  can  be  dispatched  to  a  widget  in  one  of  five 
ways.  Assume  the  server  delivered  the  event  to  the  window  for  widget  E  (due  to  X  keyboard 
focus,  key  or  keyboard  grabs,  or  pointer  position). 

•  If  neither  E  nor  any  of  E's  ancestors  have  redirected  the  keyboard  focus,  or  if  the  event 
activated   a  grab   for  E  as  specified  by  a  call  to  XtGrabKey  with  any  value  of 
owner_e vents  or  if  the  keyboard  is  actively  grabbed  by  E  with  owner_e vents 
False  via  XtGrabKeyboard  or  XtGrabKey  on  a  previous  key  press,  the  event  is 
dispatched  to  E.  (This  is  the  first  way  a  keyboard  event  can  be  dispatched.) 

•  Begin  with  the  widget  that  has  redirected  the  keyboard  focus.  This  widget  can  either  be  the 
ancestor  of  E  that  is  closest  to  the  root  or  E  itself,  if  no  such  ancestor  exists.  Then,  if  the 
target  of  that  widget's  focus  redirection  has  in  turn  redirected  the  keyboard  focus,  recur 
sively  follow  this  focus  chain  to  find  a  widget  F  that  has  not  redirected  focus. 

-  If  £  is  the  final  focus  target  widget  F  or  a  descendant  of  F,  the  event  is  dispatched  to  E. 
(This  is  the  second  way  a  keyboard  event  can  be  dispatched.) 

-  If  £  is  neither  F,  an  ancestor  of  F,  nor  a  descendant  of  F,  and  if  the  event  activated  a 
grab  for  E  as  specified  by  a  call  to  XtGrabKey  for  E,  then  xtUngrabKeyboard  is 
called. 

-  If  E  is  an  ancestor  of  F,  and  if  the  event  is  a  key  press,  and  if  either: 

+    E  has  grabbed  the  key  with  XtGrabKey  and  owner_events  set  to  False,  or 

+    E  has  grabbed  the  key  with  XtGrabKey,  owner_events  set  to  True,  and  the 
coordinates  of  the  event  are  outside  the  rectangle  specified  by  E's  geometry, 
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then  the  event  is  dispatched  to  E.  (This  is  the  third  way  a  keyboard  event  can  be 
dispatched.) 

-    Otherwise,  define  A  as  the  closest  common  ancestor  of  £  and  F.  And  in  this  case: 

+  If  there  is  an  active  keyboard  grab  for  any  widget  via  either  xtGrabKeyboard  or 
XtGrabKey  on  a  previous  key  press,  or  if  no  widget  between  F  and  A  (non-inclu 
sive)  has  grabbed  the  key  and  modifier  combination  with  XtGrabKey  and  any 
value  of  owner_e vents,  the  event  is  dispatched  to  F.  (This  is  the  fourth  way  a 
keyboard  event  can  be  dispatched.) 

+  Otherwise,  the  event  is  dispatched  to  the  ancestor  of  F  closest  to  A  that  has  grabbed 
the  key  and  modifier  combination  with  XtGrabKey.  (This  is  the  fifth  way  a  key 
board  event  can  be  dispatched.) 

When  there  is  a  modal  cascade,  if  the  final  destination  widget  as  identified  above  is  in  the 
active  subset  of  the  cascade,  the  event  is  dispatched;  otherwise,  the  event  is  re-mapped  to  a 
spring-loaded  shell  or  discarded. 

When  subtree  or  one  of  its  descendants  acquires  the  X  keyboard  focus,  or  the  pointer 
moves  into  the  subtree  such  that  keyboard  events  would  now  be  delivered  to  subtree,  a 
Focusln  event  is  generated  for  descendant  if  FocusNotif  y  events  have  been  selected 
by  descendant.  Similarly,  when  subtree  loses  the  X  keyboard  focus  or  the  keyboard 
focus  for  one  of  its  ancestors,  a  FocusOut  event  is  generated  for  descendant  if  Focus - 
Notify  events  have  been  selected  by  descendant. 

Note  that  every  widget  has  an  accept_f  ocus  method  to  allow  outside  agents  to  cause  a 
widget  to  get  the  keyboard  focus.  To  call  a  widget's  accept_f  ocus  method,  use  xtCall- 
AcceptFocus.  The  widget  returns  whether  it  actually  took  the  focus  or  not,  so  that  the  par 
ent  can  give  the  focus  to  another  widget.  Widgets  that  need  to  know  when  they  lose  the  key 
board  focus  must  use  the  Xlib  focus  notification  mechanism  explicitly  (typically  by  specifying 
translations  for  Focusln  and  FocusOut  events).  Widgets  that  need  the  keyboard  focus  can 
call  XSet  Input  Focus  explicitly.  Widgets  that  never  want  the  keyboard  focus  should  set 
their  accept_f  ocus  procedure  pointer  to  NULL. 

See  Also 

XtAddGrob(\),  XtCollAcceptFocus(\),  XtDispotchEvent(l), 

Composite(3\ 

accept Jocus  (4). 
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„  u    JU   M      XtSetKeyTranslator 

— Xt-  Keyboard  Handling J 

Name 

XtSetKeyTranslator  —  register  a  key  translator. 

Synopsis 

void  XtSetKeyTranslator (display,  proc) 
Display  ^display; 
XtKeyProc  proc; 

Arguments 

display  Specifies  the  display  from  which  to  translate  the  events. 

proc  Specifies  the  procedure  that  is  to  perform  key  translations. 

Description 

XtSetKeyTranslator  registers  the  specified  procedure  as  the  current  key  translator.  The 
default  translator  is  xtTranslateKey,  an  XtKeyProc  that  uses  the  Shift,  Lock,  and  group 
modifiers  with  the  interpretations  defined  by  the  XI 1  protocol.  XtTranslateKey  is  pro 
vided  so  that  new  translators  can  call  it  to  get  default  keycode-to-keysym  translations  and  so 
that  the  default  translator  can  be  reinstalled. 

The  only  way  to  remove  a  translator  is  to  register  a  new  one.  For  example,  the  default  key 
translator  (XtTranslateKey)  can  be  explicitly  reinstalled.  Another  approach  to  deleting  a 
converter  would  be  for  an  application  to  register  an  identity  translator  that  simply  copied  the 
input  keysym  to  both  output  keysyms. 

For  a  more  detailed  discussion  of  processing  keyboard  input,  see  Chapter  13,  Miscellaneous 
Toolkit  Programming  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 

See  Also 

XtConvertCase(\),  XtGetKeysymTable(\),  XtKeysymToKeycodeList(l\  XtRegisterCaseConverter(\\  Xt- 
TranslateKeycode  ( 1 ),  XfTranslateKey  ( 1 ), 
XtKeyProc  (2). 
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Name 

XtSetMappedWhenManaged  —  change  the  value  of  a  widget's  map_when_managed  field. 

Synopsis 

void  XtSetMappedWhenManaged (w,  map_when_managed) 
Widget  w; 
Boolean  map_when_managed; 

Arguments 

w  Specifies  the  widget 

map_ wh en_ma naged 

Specifies  a  Boolean   value  that  indicates   the  new   value  of  the  map_ 
when_managed  field. 

Description 

After  a  widget  is  realized,  it  must  be  mapped  before  it  can  become  visible.  XtSetMapped 
WhenManaged  controls  whether  this  mapping  occurs  automatically  (by  default  it  does). 

If  the  widget  is  realized  and  managed  and  if  map_when_managed  is  set  to  True,  XtSet 
MappedWhenManaged  maps  the  window.  If  the  widget  is  realized  and  managed  and  if  the 
new  value  of  map_when_managed  is  set  to  False,  XtSetMappedWhenManaged 
unmaps  the  window. 

XtSetMappedWhenManaged  is  a  convenience  function  that  is  equivalent  to  (but  slightly 
faster  than)  calling  XtSetValues  and  setting  the  new  value  for  the  xtNmappedWhen- 
Managed  resource.  As  an  alternative  to  using  XtSetMappedWhenManaged  to  control 
mapping,  a  client  may  set  XtNmappedWhenManaged  to  False  and  use  XtMapWidget  and 
XtUnmapWidget  explicitly. 

A  widget  is  normally  mapped  if  it  is  managed.  However,  this  behavior  can  be  overridden  by 
setting  the  Core  XtNmappedWhenManaged  resource  for  the  widget  when  it  is  created  or  by 
setting  the  map_when_managed  field  to  False. 

See  Also 

XtCreoteManagedWidget(l),  XtManageChtidren(\\  XtMapWidget(l),  XtSetValues (\\  XtUnmap- 
Widget(l). 
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„  u    JU   ,„  XtSetMultiClickTime 

— Xt-  Keyboard  Handling 

Name 

XtSetMultiClickTime  —  set  the  multi-click  time  dynamically. 

Synopsis 

void  XtSetMultiClickTime (dpy,  time) 
Display  *  display; 
int  time; 

Arguments 

display  Specifies  the  display  connection. 

time  Specifies  the  multi-click  time  in  milliseconds. 

Description 

XtSetMultiClickTime  sets  the  time  interval  used  by  the  translation  manager  to  determine 
when  multiple  events  are  interpreted  as  a  repeated  event.  When  a  repeat  count  is  specified  in  a 
translation  entry  the  time  interval  between  arrival  of  each  pair  of  repeated  events  (e.g.,  between 
two  ButtonPress  events)  must  be  less  than  the  multi-click  time  in  order  for  the  translation 
actions  to  be  taken. 

Translation  table  entries  may  specify  actions  that  are  taken  when  two  or  more  identical  events 
occur  consecutively,  separated  by  a  short  time  interval  called  the  multi-click  time.  The  multi- 
click  time  value  can  be  specified  as  an  application  resource  with  name  multiClickTime 
and  class  MultiClickTime;  the  multi-click  time  value  can  also  be  modified  dynamically  by 
the  application.  The  multi-click  time  is  unique  for  each  Display  and  is  retrieved  from  the 
resource  database  by  xtDi  splay  Initialize.  If  no  value  is  specified,  the  initial  value  is 
200  milliseconds. 

See  Also 

XtGetMultlClickTime(\) 
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•Xt-  Selections- 


Name 

XtSetSelectionTimeout  —  set  value  of  selection  timeout. 

Synopsis 

void  XtSetSelectionTimeout ( timeout) 
unsigned  long  timeout; 

Arguments 

timeout  Specifies  the  selection  timeout  in  milliseconds. 

Description 

XtSetSelectionTimeout  has  been  superseded  by  XtAppSetSelectionTimeout. 
timeout  is  the  time  within  which  the  two  communicating  applications  must  respond  to  one 
another.  If  one  of  them  does  not  respond  within  this  interval,  Xt  aborts  the  selection  request. 
The  default  value  of  timeout  is  5000  milliseconds  (five  seconds). 

Chapter  10,  Inter  client  Communications,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming 
Manual,  presents  a  complete  example  widget  that  both  sends  and  receives  data  using  selections. 
Note,  however,  that  XtSetSelectionTimeout  is  normally  called  by  an  application,  not  by 
a  widget 

See  Also 

XtGetSelectionTimeout  ( 1 ) 
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. f  XtSetSensitive 

— Xt  -  Resource  Management 

Name 

XtSetSensitive  —  set  the  sensitivity  state  of  a  widget. 

Synopsis 

void  XtSetSensitive (w,  sensitive) 
Widget  w; 
Boolean  sensitive; 

Arguments 

w  Specifies  the  widget 

sensitive          Specifies  a  Boolean  value  that  indicates  whether  the  widget  should  receive 
keyboard,  pointer,  and  focus  events. 

Description 

Many  widgets  have  a  mode  in  which  they  assume  a  different  appearance  (for  example,  grayed 
out  or  stippled),  do  not  respond  to  user  events,  and  become  dormant. 

When  dormant,  a  widget  is  insensitive.  This  means  that  the  Intrinsics  do  not  dispatch  any 
events  to  the  widget  with  an  event  type  of  KeyPress,  KeyRelease,  ButtonPress, 
ButtonRelease,  MotionNotify,  EnterNotify,  LeaveNotify,  Focusln,  or 
FocusOut. 

Widget  sensitivity  is  controlled  by  the  sensitive  and  ancestor_sensitive  fields  in 
the  Core  instance  record.  The  former  is  set  with  the  xtNsensitive  resource;  the  latter's 
resource,  xtNancestorSensitive,  should  only  be  queried.  A  widget  can  be  insensitive 
because  its  sensitive  field  is  False  or  because  one  of  its  ancestors  is  insensitive  (sensi 
tive  is  always  set  to  False  if  ancestor_sensitive  is  False).  A  widget  can,  but  does 
not  need  to,  distinguish  these  two  cases  visually. 

XtSetSensitive  first  calls  XtSetValues  on  the  current  widget  with  an  argument  list 
specifying  the  sensitive  resource  and  the  new  value.  If  sensitive  is  False  and  the  widget 
is  a  subclass  of  Composite,  XtSetSensitive  recursively  propagates  the  new  value  down 
the  children  tree  by  calling  XtSetValues  on  each  child  to  set  ancestor_sensitive  to 
False.  If  sensitive  is  True  and  the  widget  is  a  subclass  of  Composite  and  the  widget's 
ancestor_sensitive  field  is  True,  then  XtSetSensitive  sets  the  ancestor_sen- 
sitive  of  each  child  to  True  and  then  recursively  calls  XtSetValues  on  each  normal 
descendant  that  is  now  sensitive  to  set  ancestor_sensitive  to  True. 

XtSetSensitive  calls  XtSetValues  to  change  the  sensitive  and  ancestor_sen- 
sitive  fields  in  Core.  Therefore,  when  one  of  these  changes,  the  widget's  set_values 
method  should  take  whatever  display  actions  are  needed  (for  example,  graying  or  stippling  the 
widget). 

XtSetSensitive  ensures  that  if  a  parent  has  either  sensitive  or  ancestor_sensi- 
tive  set  to  False,  then  all  children  have  ancestor_sensitive  set  to  False. 

Both  sensitive  and  the  ancestor_sensitive  field  are  maintained  as  Booleans  in  the 
Core  instance  record,  defined  in  <Xll/CoreP.h>. 
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See  Also 

XtGetValues(\\  XtIsSensitive(\\  XtSetValues(l). 
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— Xt  -  Resource  Management- 


XtSetSubvalues 


Name 

XtSetSubvalues  —  copy  resource  settings  from  an  ArgList  to  a  subpart  resource  list. 

Synopsis 

void  XtSetSubvalues (base,  resources,  num_resources,  args,  num_args) 
XtPointer  base; 
XtResourceList  resources; 
Cardinal  nu/n_resources; 
ArgList  args; 
Cardinal  num  args; 


Arguments 

base 


Specifies  the  base  address  of  the  subpart  data  structure  into  which  the 
resources  should  be  written. 


resources         Specifies  the  nonwidget  resource  list. 

/ju/n_resources  Specifies  the  number  of  resources  in  the  resource  list. 

args  Specifies  the  argument  list  of  name/value  pairs  that  contain  the  resource  set- 


num  args 


tings  to  be  copied  into  the  subpart  data  structure. 
Specifies  the  number  of  arguments  in  the  argument  list. 


Description 

XtSetSubvalues  copies  resource  settings  from  the  specified  argument  list  into  the  structure 
identified  by  base.  The  resource  list  specifies  which  resource  settings  are  copied  and  into 
which  fields  of  the  structure  pointed  to  by  base. 

XtSetSubvalues  is  normally  called  only  from  the  set_values  method  of  a  widget  with 
subparts.  It  can  never  be  called  from  the  application  because  the  application  does  not  have  the 
subpart  resource  list. 

The  conjugate  function  xtGetSubvalues  gets  a  subpart's  resource  values. 

Structures 

xtResource  is  defined  as  follows  in  <XlllInstrinsic.h>: 


typedef  struct  _XtResource  { 
String    resource_name; 
String    resource_class; 
String    resource_type; 
Cardinal   resource  size; 


/*  Resource  name  */ 

/*  Resource  class  */ 

/*  Representation  type  desired  */ 

/*  Size  in  bytes  of  representation  */ 

resource_offset;/*  Offset  from  base  to  put  resource  value  */ 

/*  Representation  type  of  specified  default  */ 

/*  Address  of  resource  default  value  */- 


Cardinal 

String    default_type; 

XtPointer  default  addr; 


}  XtResource,  *XtResourceList ; 
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Arg  are  defined  as  follows  in  <X1  II Intrinsic. h>: 

typedef  struct  { 

String  name; 

XtArgVal  value; 
}  Arg,  *ArgList; 

See  Also 

set  values  (4) 
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—  Xt  -  Resource  Management  - 


J  XtSetTypeConverter 


Name 

XtSetTypeConverter  —  register  a  type  converter  for  all  application  contexts  in  a  process. 

Synopsis 

void  XtSetTypeConverter (from_type,  to_type,  converter,  convert_args, 

num_args,  cache_type,  destructor) 
String  from_type,  to_type; 
XtTypeConverter  converter; 
XtConvertArgList  convert_args; 
Cardinal  num_args; 
XtCacheType  cache_type; 
XtDestructor  destructor; 

Arguments 

from_type          Specifies  the  source  type. 

to_type  Specifies  the  destination  type. 

converter  Specifies  the  resource  type  converter  procedure. 

convert_args  Specifies  additional  conversion  arguments,  or  NULL. 

num_args  Specifies  the  count  of  additional  conversion  arguments,  or  zero. 

cache_type  Specifies  whether  or  not  resources  produced  by  this  converter  are  sharable  or 
display-specific  and  when  they  should  be  freed. 

destructor  Specifies  a  destroy  procedure  for  resources  produced  by  this  conversion,  or 
NULL  if  no  additional  action  is  required  to  deallocate  resources  produced  by 
converter. 

Description 

XtSetTypeConverter  supersedes  XtAddConverter.  XtSetTypeConverter  regis 
ters  the  specified  type  converter  and  destructor  in  all  application  contexts  created  by  the  calling 
process,  including  any  future  application  contexts  which  may  be  created.  (xtAppSetType- 
Converter  registers  the  specified  type  converter  in  the  single  application  context  specified.) 
If  the  same  from_type  and  to_type  are  specified  in  multiple  calls  to  either  function,  the 
most  recent  overrides  the  previous  ones. 

Structures 

Conversion  cache  control  is  specified  via  an  XtCacheType  argument. 

typedef  int  XtCacheType; 

The  xtConvertArgRec  structure  is  defined  in  <X1 1  /Convert. h>. 

typedef  struct  { 

XtAddressMode  address_mode; 

XtPointer  address_id; 

Cardinal  size; 
}  XtConcertArgRec,  * XtConvertArgList ; 
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See  Also 

XtAppSe(TypeConverter(l),  XtCallConverter(\\  XtConvertAndStore(\\ 
XtDestructor  (2),  XfTypeConverter  (2). 
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-Xt-  Resource  Management '  XtSetValUGS 

Name 

XtSet Values  —  copy  resources  from  an  ArgList  to  a  widget 

Synopsis 

void  XtSetValues (object,  args,  num_args) 
Widget  object; 
ArgList  args; 
Cardinal  num_args; 

Arguments 

object  Specifies  the  object  whose  resources  are  to  be  modified;  may  be  of  class 

Object  or  any  subclass  thereof. 

args  Specifies  the  argument  list  of  name/value  pairs  that  contain  the  resources  to 

be  modified.  The  resources  and  values  passed  depend  on  the  widget  being 
modified. 

num_args  Specifies  the  number  of  arguments  in  the  argument  list. 

Description 

XtSetValues  modifies  the  current  state  of  resources  associated  with  a  widget  instance.  The 
widget  decides  what  changes  it  will  actually  allow  and  updates  all  derived  fields  appropriately. 

The  name  fields  in  args  contain  the  names  of  resources.  The  value  fields  in  args  contain  the 
new  values  of  resources. 

XtSetValues  starts  with  the  resources  specified  for  the  Core  widget  fields  and  descends  the 
subclass  chain  to  the  widget  At  each  stage,  it  copies  the  new  value  (if  specified  in  args)  or 
the  existing  value  (if  no  new  value  is  specified)  to  a  new  widget  instance  record.  XtSet 
Values  then  calls  the  set_values  methods  for  the  widget  in  superclass-to-subclass  order. 
If  the  widget  has  any  non-NULL  set_values_hook  fields,  these  methods  are  called  immedi 
ately  after  the  corresponding  set_values  method.  (Note,  however,  that  set_val- 
ues_hook  is  outmoded;  its  code  is  now  placed  in  set_values.)  This  permits  access  to 
subpart  resource  data  from  XtSetValues. 

If  the  widget's  parent  is  a  subclass  of  constraintwidgetClass,  XtSetValues  also 
updates  the  widget's  constraints.  It  starts  with  the  constraint  resources  specified  for 
constraintwidgetClass  and  proceeds  down  the  subclass  chain  to  the  parent's  class.  At 
each  stage,  it  writes  the  new  value  or  the  existing  value  to  a  new  constraint  record.  It  then  calls 
the  constraint  set_values  methods  from  constraintwidgetClass  down  to  the  par 
ent's  class.  The  constraint  set_values  methods  are  called  with  widget  arguments,  as  for  all 
set_values  methods,  not  just  the  constraint  record  arguments,  so  that  they  can  make  adjust 
ments  to  the  desired  values  based  on  full  information  about  the  widget. 

XtSetValues  determines  if  a  geometry  request  is  needed  by  comparing  the  current  widget  to 
the  new  widget  If  any  geometry  changes  are  required,  it  makes  the  request,  and  the  geometry 
manager  returns  XtGeometryYes,  XtGeometryAlmost,  or  XtGeometryNo.  If  xt- 
GeometryYes  is  returned,  XtSetValues  calls  the  widget's  resize  method.  If  Xt 
GeometryNo  is  returned,  XtSetValues  resets  the  geometry  fields  to  their  original  values. 
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If  xtGeometryAlmost  is  returned,  XtSetValues  calls  the  set_values_almost 
method,  which  determines  what  should  be  done  and  writes  new  values  for  the  geometry  fields 
into  the  new  widget  XtSetValues  then  repeats  this  process,  deciding  once  more  whether 
the  geometry  manager  should  be  called. 

Finally,  if  any  of  the  set_values  methods  returned  True,  XtSetValues  causes  the 
widget's  expose  method  to  be  invoked  by  calling  the  Xlib  XClearArea  function  on  the 
widget's  window. 

The  conjugate  function  xtGetValues  retrieves  a  widget's  values. 

Structures 

Arg  is  defined  as  follows  in  <X11 /Intrinsic. h>: 

typedef  struct  { 

String  name; 

XtArgVal   value; 
}    Arg,    *ArgList; 

See  Also 

XtSetArgd), 

set_values(4),  set_values_hook(4). 
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c     u         J  XtSetWarningHandler 

— Xt-  Error  Handling ' 

Name 

XtSetWarningHandler  —  register  a  procedure  to  be  called  on  nonfatal  error  conditions. 

Synopsis 

void  XtSetWarningHandler (handler) 
XtErrorHandler  handler; 

Arguments 

handler  Specifies  the  new  low-level  nonfatal  error  procedure,  which  usually  returns. 

Description 

XtSetWarningHandler  has  been  superseded  by  XtAppSetWarningHandler.  The 
Intrinsics  let  a  client  register  procedures  that  are  to  be  called  whenever  a  fatal  or  nonfatal  error 
occurs.  These  facilities  are  intended  for  both  error  reporting  and  logging  and  for  error  correc 
tion  or  recovery. 

Two  levels  of  interface  are  provided: 

•  A  high-level  interface  that  takes  an  error  name  and  class  and  looks  the  error  up  in  an 
error  resource  database.  The  high-level  fatal  error  handler  is  invoked  by  a  call  to  xt  - 
ErrorMsg  or  xtAppErrorMsg;  the  high-level  nonfatal  error  handler  is  invoked  by  a 
call  to  XtWarningMsg  or  XtAppWarningMsg.  A  new  handler  can  be  registered  by 
calling    XtSetErrorMsgHandler,   XtAppSetErrorMsgHandler,   or  XtApp- 
SetWarningMsgHandler. 

•  A  low-level  interface  that  takes  a  simple  string,  which  is  printed  out  as  the  error  message. 
The  low-level  fatal  error  handler  is  invoked  by  a  call  to  xtError  or  xtAppError;  the 
low-level  nonfatal  error  handler  is  invoked  by  a  call  to  xtWarning  or  xtApp- 
Warning.  A  new  handler  can  be  registered  by  calling  xtSetErrorHandler,  Xt 
SetWarningHandler,     XtAppSetErrorHandler,     or     XtAppSetWarning 
Handler. 

The  high-level  functions  construct  a  string  to  pass  to  the  lower-level  interface.  On  POSDC- 
based  systems,  the  error  database  is  usually  lusrlliblXHIXtErrorDB. 

To  obtain  the  error  database  (for  example,  to  merge  with  an  application  or  widget-specific  data 
base),  use  XtAppGetErrorDatabase. 

Application-con  text-specific  error  handling  is  not  implemented  on  many  systems.  Most  imple 
mentations  will  have  just  one  set  of  error  handlers.  If  they  are  set  for  different  application  con 
texts,  the  one  set  last  will  prevail. 

The  default  warning  handler  provided  by  the  Intrinsics  is  _XtWarning.  On  POSDC-based  sys 
tems,  it  prints  the  message  to  standard  error  and  returns  to  the  caller.  Using  XtAppSet 
WarningHandler,  you  can  replace  this  handler  with  one  of  your  own. 

Warning  message  handlers  should  return.  If  an  error  is  non-recoverable,  an  application  should 
generate  a  fatal  error. 
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See  Also 

XtSetErrorHandler(\\  XtSetWarningMsgHandler(\),  XtWarning(\\ 
XtErrorHandler  (2),  XtErrorMsgHandler  (2). 
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— Xt-  Error  Handling 


J  XtSetWarningMsgHandler 


Name 

XtSetWarningMsgHandler  —  register  a  high-level  procedure  to  be  called  on  nonfatal  error  con 
ditions. 

Synopsis 

void  XtSetWarningMsgHandler (msg_handler) 
XtErrorMsgHandler  msg_handler; 

Arguments 

msg_handler      Specifies  the  new  high-level  nonfatal  error  procedure,  which  usually  returns. 

Description 

XtSetWarningMsgHandler  has  been  superseded  by  XtAppSetWarningMsgHandler. 
The  Intrinsics  let  a  client  register  procedures  that  are  to  be  called  whenever  a  fatal  or  nonfatal 
error  occurs.  These  facilities  are  intended  for  both  error  reporting  and  logging  and  for  error 
correction  or  recovery. 

Two  levels  of  interface  are  provided: 

•  A  high-level  interface  that  takes  an  error  name  and  class  and  looks  the  error  up  in  an 
error  resource  database.   The  high-level  fatal  error  handler  is  invoked  by  a  call  to  xt- 
ErrorMsg  or  xtAppErrorMsg;  the  high-level  nonfatal  error  handler  is  invoked  by  a 
call  to  XtWarningMsg  or  XtAppWarningMsg.  A  new  handler  can  be  registered  by 
calling    XtSetErrorMsgHandler,   XtAppSetErrorMsgHandler,   or  XtApp 
SetWarningMsgHandler. 

•  A  low-level  interface  that  takes  a  simple  string,  which  is  printed  out  as  the  error  message. 
The  low-level  fatal  error  handler  is  invoked  by  a  call  to  xt Error  or  xtAppError;  the 
low-level  nonfatal  error  handler  is  invoked  by  a  call  to  XtWarning  or  xtApp- 
Warning.  A  new  handler  can  be  registered  by  calling  xtSetErrorHandler,  xt- 
SetWarningHandler,        XtAppSetErrorHandler,        XtAppSetWarning- 
Handler. 

The  high-level  functions  construct  a  string  to  pass  to  the  lower-level  interface.  On  POSEX- 
based  systems,  the  error  database  is  usually  lusrlliblXlllXtErrorDB. 

To  obtain  the  error  database  (for  example,  to  merge  with  an  application  or  widget-specific  data 
base),  use  XtAppGetErrorDatabase. 

Application-context-specific  error  handling  is  not  implemented  on  many  systems.  Most  imple 
mentations  will  have  just  one  set  of  error  handlers.  If  they  are  set  for  different  application  con 
texts,  the  one  set  last  will  prevail. 

The  default  warning  handler  provided  by  the  Intrinsics  constructs  a  string  from  the  error 
resource  database  and  calls  XtAppWarning.  Using  XtAppSetWarningMsgHandler, 
you  can  replace  this  default  handler  with  one  of  your  own. 

See  Also 

XtSetErrorHondlerd),  XtSetErrorMsgHandler  (I),  XtSetWarningHandler(\\  XtWarningMsg  (I), 
XtErrorMsgHandler  (2). 
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XtSetWMColormapWindows 

Xt  -  Properties— 

Name 

XtSetWMColormapWindows  —  set  WM_COLORMAP_WINDOWS  property  to  inform  window 

manager  of  custom  colormaps. 

Synopsis 

void  XtSetWMColormapWindows (widget,  list,  count) 
Widget  widget; 
Widget*  list; 
Cardinal  count; 

Arguments 

widget  Specifies  the  widget  on  whose  window  the  WM_COLORMAP_WINDOWS 

property  will  be  stored. 

list  Specifies  a  list  of  widgets  whose  windows  are  to  be  listed  in  the  WM_COLOR- 

MAP_WINDOWS  property. 

count  Specifies  the  number  of  widgets  in  list. 

Description 

XtSetWMColormapWindows  returns  immediately  if  widget  is  not  realized  or  if  count  is 
0.  Otherwise,  XtSetWMColormapWindows  constructs  an  ordered  list  of  windows  by  exa 
mining  each  widget  in  the  list  in  turn  and: 

•  Ignoring  the  widget  if  it  is  not  realized  or 

•  Adding  the  widget's  window  to  the  window  list  if  the  widget  is  realized  and  if  its  color- 
map  resource  differs  from  the  colormap  resources  of  all  widgets  whose  windows  are 
already  on  the  window  list. 

Finally,  XtSetWMColormapWindows  stores  the  resulting  window  list  in  the  WM_COLOR- 
MAP_WINDOWS  property  on  the  specified  widget's  window.  This  tells  the  window  manager 
which  windows  have  a  custom  colormap,  so  that  the  window  manager  can  install  these  color- 
maps  at  the  appropriate  time. 
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— Xt-  Error  Handling- 


J          XtStringConversionWarning 


Name 

XtStringCon  version  Warning  —  emit  boilerplate  string  conversion  error  message. 

Synopsis 

void   XtStringConversionWarning (src,    dst_type) 
String   src,    dst_type; 

Arguments 

src  Specifies  the  string  that  could  not  be  converted. 

dst_type  Specifies  the  name  of  the  type  to  which  the  string  could  not  be  converted. 

Description 

XtStringConversionWarning  has  been  superseded  by  XtDisplayString- 
ConversionWarning.  XtStringConversionWarning  is  a  convenience  routine  for 
use  in  old-style  resource  converters  that  convert  from  strings.  It  issues  a  warning  message  with 
the  name  conversionError,  type  string,  class  XtToolkitError,  and  default  mes 
sage  string: 

"Cannot   convert    src  to   type    dst_type" 

It  can  be  used  by  a  conversion  routine  to  announce  a  nonfatal  conversion  error. 

See  Also 

XtDisplayStringConversioriWarning(\) 


X  Toolkit  Intrinsics  Reference  Manual  335 


XtSuperclass  V 

v Xt  -  Object  Information  — 

Name 

XtSuperclass  —  obtain  a  widget's  superclass. 

Synopsis 

WidgetClass  XtSuperclass ( object) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  superclass  is  to  be  returned;  may  be  of  class 

Object  or  any  subclass  thereof. 

Description 

XtSuperclass  returns  a  pointer  to  the  class  structure  of  the  widget's  superclass. 

See  Also 

XtCheckSubclass(l),  XtClass(l),  XtIsSubclass(l), 
Core  (3). 
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„  ..    „  .  # /  XtToolkitlnitialize 

— Xt  -  Application  Contexts ' 

Name 

XtToolkitlnitialize  —  initialize  the  X  Toolkit  internals. 

Synopsis 

void  XtToolkitlnitialize () 

Description 

XtToolkitlnitialize  initializes  internal  Toolkit  data  structures.  It  does  not  set  up  an 
application  context  or  open  a  display. 

XtAppInitialize  calls  XtToolkitlnitialize  in  the  course  of  its  initialization.  Pro 
grams  too  sophisticated  to  use  XtAppInitialize  (such  as  those  that  create  multiple  appli 
cation  contexts)  may  want  to  call  XtToolkitlnitialize  explicitly. 

The  semantics  of  calling  XtToolkitlnitialize  more  than  once  are  undefined. 
See  Also 

XtAppInitialize  ( 1 ) 
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XtTranslateCoords  \ V1 

v Xt  -  Window  Manipulation  — 

Name 

XtTranslateCoords  —  translate  an  x-y  coordinate  pair  from  widget  coordinates  to  root  coordi 
nates. 

Synopsis 

void  XtTranslateCoords (w,  x,  y,  root_x_return,  root_y_return) 
Widget  w; 
Position  x,  y; 
Position  * root_x_return,  *  root_y_return; 

Arguments 

w  Specifies  the  widget. 

x,  y  Specify  the  widget-relative  x  and  y  coordinates. 

root_x_return,  root_y_return 

Return  the  root-relative  x  and  y  coordinates. 

Description 

XtTranslateCoords  converts  widget-relative  coordinates  to  screen-relative  coordinates. 
This  is  useful  in  popping  up  a  pop-up  shell,  since  it  must  be  explicitly  moved  from  its  default 
location  at  the  upper-left  corner  of  the  screen. 

The  display  height  and  width  can  be  obtained  in  pixels  with  the  Xlib  macros  XDi splay- 
Height  and  XDisplayWidth,  and  in  millimeters  with  the  Xlib  macros  XDisplay- 
HeightMM  and  XDisplayWidthMM. 

These  macros  require  a  display  and  screen,  which  can  be  returned  by  Intrinsics  functions.  An 
example  might  be: 

height   =  XDisplayHeight (XtDisplay (w) ,    XtScreen (w) ) ; 

XtTranslateCoords  is  similar  to  the  Xlib  XTranslateCoordinates  function,  which 
also  translates  window-relative  coordinates  to  display-relative  coordinates.  But  Xt 
TranslateCoords  does  not  usually  generate  a  server  request  because  most  of  the  time  the 
required  information  is  already  in  the  widget's  data  structures. 

See  Also 

Core 
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—Xt- Keyboard  Handling 


J  XtTranslateKey 


Name 

XtTranslateKey  —  the  default  keycode-to-keysym  translator. 

Synopsis 

void  XtTranslateKey (display,  keycode,  modifiers, 

modi fiers_ret urn,  keysym_return) 
Display  *  display; 
KeyCode  keycode; 
Modifiers  modifiers; 
Modifiers  *modifiers_return; 
KeySym  * keysym_return; 

Arguments 

display  Specifies  the  display  that  the  keycode  is  from. 

keycode  Specifies  the  keycode  to  translate. 

modifiers         Specifies  the  modifiers  to  be  applied  to  the  keycode. 

modi fi ers_re t urn 

Returns  a  mask  that  indicates  the  modifiers  actually  used  to  generate  the 
keysym  (an  AND  of  modifiers  and  any  default  modifiers  applied  by  the 
currently  registered  translator). 

keysym_return  Returns  the  resulting  keysym. 

Description 

XtTranslateKey  is  the  default  XtKeyProc.  It  takes  a  keycode  and  returns  the  corre 
sponding  keysym,  recognizing  Shift  and  Lock  modifiers.  XtTranslateKey  is  provided  for 
two  main  reasons:  so  that  new  translators  with  expanded  functionality  can  call  it  to  get  default 
keycode-to-keysym  translations  in  addition  to  whatever  they  add,  and  so  that  the  default  trans 
lator  can  be  reinstalled. 

The  default  key  translator  can  be  invoked  directly  by  calling  xtTranslateKeycode.  A 
new  translator  can  be  registered  by  calling  xtSetKeyTranslator.  There  is  no  way  to 
remove  a  translator;  to  reinstall  the  default  behavior,  call  XtSetKeyTranslator  with  Xt 
TranslateKey  as  the  proc  argument 

Structures 

typedef  unsigned  int  Modifiers; 

Modifiers  will  be  made  up  of  the  bitwise  OR  of  the  following  masks: 
Shi  f  tMa  s  k  Shift  key  was  depressed. 

LockMa s k  Caps  Lock  key  was  depressed. 

ControlMask         Control  key  was  depressed. 
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ModlMask  Key  defined  as  Modi  was  depressed. 


ModSMask  Key  defined  as  Mod5  was  depressed. 

StandardMask        (ShiftMask    |    LockMask). 

See  Also 

XtRegisterCaseConverter  ( 1 ),  XtSetKeyTranslator  ( 1 ),  XfTranslateKeycode  ( 1 ), 
XtKeyProcQ.). 
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— Xt  -  Keyboard  Handling- 


XtTranslateKeycode 


Name 

XtTranslateKeycode  —  invoke  the  currently  registered  keycode-to-keysym  translator. 

Synopsis 

void  XtTranslateKeycode (display,  keycode,  modifiers,  modifiers_return, 

keysym_return ) 
Display  *display; 
KeyCode  keycode; 
Modifiers  modifiers; 
Modifiers  *modifiers_return; 
KeySym  * keysym_return; 

Arguments 

display  Specifies  the  display  that  the  keycode  is  from. 

keycode  Specifies  the  keycode  to  translate. 

modifi  ers         Specifies  the  modifiers  to  be  applied  to  the  keycode. 

modi  fi  ers_re  t  urn 

Returns  a  mask  that  indicates  the  modifiers  actually  used  to  generate  the 
keysym  (an  AND  of  modifiers  and  any  default  modifiers  applied  by  the 
currently  registered  translator). 

keysym_return  Returns  the  resulting  keysym. 

Description 

XtTranslateKeycode  is  used  to  invoke  the  currently  registered  keycode-to-keysym  trans 
lator  (xtTranslateKey  by  default).  It  passes  its  arguments  directly  to  that  converter.  The 
translator  is  registered  by  a  call  to  xtSetKeyTranslator. 

The  various  functions  for  changing  keyboard  mapping  are  discussed  in  Chapter  13,  Miscella 
neous  Toolkit  Programming  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming 
Manual. 

Structures 

typedef  unsigned  int  Modifiers; 

Modifiers  will  be  made  up  of  the  bitwise  OR  of  the  following  masks: 


ShiftMask 
LockMask 
ControlMask 
ModlMask 


Shift  key  was  depressed. 

Caps  Lock  key  was  depressed. 

Control  key  was  depressed. 

Key  defined  as  Modi  was  depressed. 
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Mod5Mask  Key  defined  as  Mod5  was  depressed. 

StandardMask        (ShiftMask    |    LockMask). 

See  Also 

XtRegisterCaseConverter(\\  XtSetKeyTranslator(\),  X(TranslateKey(l), 
XtKeyProc(2). 
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— Xt-  Pointer- 


XtUngrabButton 


Name 

XtUngrabButton  —  cancel  a  passive  button  grab. 

Synopsis 

void  XtUngrabButton (widget,  button,  modifiers) 
Widget  widget; 
unsigned  int  button; 
Modifiers  modifiers; 


Arguments 

widget 
button 


Specifies  the  widget  in  whose  window  the  button  was  grabbed. 

Specifies  the  mouse  button  to  be  released  from  grab.  Specify  Buttonl, 
Button2,  Buttons,  Button4,  Buttons,  or  the  constant  AnyButton, 
which  is  equivalent  to  issuing  the  ungrab  request  for  all  possible  buttons. 

modifiers  Specifies  a  set  of  keymasks.  This  is  a  bitwise  OR  of  one  or  more  of  the  fol 
lowing  symbols:  ShiftMask,  LockMask,  ControlMask,  ModlMask, 
Mod2Mask,  Mod3Mask,  Mod4Mask,  ModSMask,  or  AnyModifier. 
AnyModif  ier  is  equivalent  to  issuing  the  ungrab  button  request  for  all  pos 
sible  modifier  combinations  (including  no  modifiers). 

Description 

The  XtUngrabButton  procedure  calls  XUngrabButton  specifying  the  widget's  window 
as  the  ungrab  window,  if  the  widget  is  realized.  The  remaining  arguments  are  exactly  as  for 
XUngrabButton.  If  the  widget  is  not  realized,  XtUngrabButton  removes  a  deferred  xt- 
GrabButton  request,  if  any,  for  the  specified  widget,  button,  and  modifiers. 

See  Also 

XtGrabButton(\\  XtGrabKey(\\  XtGrabKeyboard(\),  XtGrabPointer(\\  XtSetKeyboardFocus(\\  Xt- 
UngrabKey(l),  XtUngrabKeyboard(\\  XtUngrabPointer(\). 
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XtUngrabKey  \ Vl 

> Xt  -  Keyboard  Handling- 
Name 

XtUngrabKey  —  cancel  a  passive  key  grab. 

Synopsis 

void  XtUngrabKey (widget,  keycode,  modifiers) 
Widget  widget; 
KeyCode  keycode; 
Modifiers  modifiers; 

Arguments 

wi  dget  Specifies  the  widget  in  whose  window  the  key  was  grabbed. 

keycode  Specifies  the  keycode.   This  keycode  maps  to  the  specific  key  you  want  to 

ungrab.  Pass  either  a  keycode  or  Any  Key. 

modifiers  Specifies  a  set  of  keymasks.  This  is  a  bitwise  OR  of  one  or  more  of  the  fol 
lowing  symbols:  ShiftMask,  LockMask,  ControlMask,  ModlMask, 
Mod2Mask,  ModSMask,  Mod4Mask,  ModSMask,  or  AnyModifier. 
AnyModif  ier  is  equivalent  to  issuing  the  ungrab  key  request  for  all  pos 
sible  modifier  combinations  (including  no  modifiers). 

Description 

The  XtUngrabKey  procedure  calls  XUngrabKey  specifying  the  widget's  window  as  the 
ungrab  window,  if  the  widget  is  realized.  The  remaining  arguments  are  exactly  as  for 
XUngrabKey.  If  the  widget  is  not  realized  XtUngrabKey  removes  a  deferred  XtGrabKey 
request,  if  any,  for  the  specified  widget,  keycode  and  modifiers. 

See  Also 

XtGrabButton(\\  XtGrabKey(\\  XtGrabKeyboard(\\  XtGrabPolnter(\\  XtSetKeyboardFocus(\\  Xt- 
UngrabButton(l),  XtUngrabKeyboard(\\  XtUngrabPointer(\). 
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—Xt-  Keyboard  Handling 


XtUngrabKeyboard 


Name 

XtUngrabKeyboard  —  cancel  an  active  keyboard  grab. 

Synopsis 

void   XtUngrabKeyboard (widget,    time) 
Widget    widget; 
Time    time; 


Arguments 

widget 
time 


Specifies  the  widget  which  has  the  active  keyboard  grab. 

Specifies  the  time.  Pass  either  a  timestamp,  expressed  in  milliseconds,  or  the 
constant  CurrentTime.  If  this  time  is  earlier  than  the  last-keyboard-grab 
time  or  later  than  the  current  server  time  the  keyboard  will  not  be  ungrabbed. 


Description 

XtUngrabKeyboard  calls  XUngrabKeyboard  with  the  specified  time. 

See  Also 

XtGrabButton(l\  XtGrabKeyd),  XtGrabKeyboard(\\  XtGrabPointer(l\  XtSetKeyboardFocus(\\  Xt- 
UngrabButton(l),  XtUngrabKey(l),  XtUngrabPoinler(\). 
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XtUngrabPointer  . 

v Xt  -  Pointer— 

Name 

XtUngrabPointer  —  cancel  an  active  pointer  grab. 

Synopsis 

void  XtUngrabPointer ( widget,  time) 
Widget  widget; 
Time  time; 

Arguments 

widget  Specifies  the  widget  which  has  the  active  pointer  grab. 

time  Specifies  the  time.  Pass  either  a  timestamp,  expressed  in  milliseconds,  or  the 

constant  CurrentTime.  If  this  time  is  earlier  than  the  last-keyboard-grab 
time  or  later  than  the  current  server  time  the  keyboard  will  not  be  ungrabbed. 

Description 

XtUngrabPointer  calls  XUngrabPointer  with  the  specified  time. 

See  Also 

XtGrabButton(\\  XtGrabKey(\\  XtGrabKeyboard(l),  XtGrabPointer(\\  XtSetKeyboardFocus(\\  Xt- 
UngrabButton(l),  XtUngrabKey(\\  XtUngrabKeyboard(l). 
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XtUninstallTranslations 

— Xt  -  Translations  and  Actions- 

Name 

XtUninstallTranslations  —  remove  existing  translations. 

Synopsis 

void  XtUninstallTranslations (w) 
Widget    w; 

Arguments 

w  Specifies  the  widget  from  which  the  translations  are  to  be  removed. 

Description 

XtUninstallTranslations  removes  a  widget's  translation  table.  This  might  be  useful  to 
eliminate  all  of  a  widget's  translations,  perhaps  for  debugging  or  testing. 

To  replace  a  widget's  translations  completely  and  not  just  selectively  overwrite  some  of  them, 
use  xtSetValues  on  the  xtNtranslations  resource  and  specify  a  compiled  translation 
table  as  the  value. 

To  merge  new  translations  with  existing  translations,  use  xtAugmentTranslations  or 
XtOverrideTranslations . 

See  Also 

XtAugmenfTranslations(\),  XtOverrideTranslations (1),  XtParseTranslationTable(\),  XtSetValues(\). 
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XtUnmanageChild 

v Xt  -  Geometry  Management — 

Name 

XtUnmanageChild  —  remove  a  widget  from  its  parent's  managed  list. 

Synopsis 

void  XtUnmanageChild (w) 
Widget  w; 

Arguments 

w  Specifies  the  child  widget  to  be  unmanaged. 

Description 

XtUnmanageChild   constructs   a   widget   list  containing   one  element   and   calls   xt- 

UnmanageChildren. 

Note  that  XtManageChild,  XtManageChildren,  XtUnmanageChild,  and  Xt- 
UnmanageChildren  are  low-level  routines  that  are  used  by  generic  composite  widget  build 
ing  routines.  In  addition,  composite  widgets  can  provide  widget-specific,  high-level  conve 
nience  procedures  to  let  applications  create  and  manage  children  more  easily. 

See  Also 

XtDestroyWidget(\\  XtIsManaged(l\  XtManageChild(\\  XtManageChildren(\\  XtUnmanage- 
Children(l). 
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— Xt  -  Geometry  Management- 


J  XtUnmanageChildren 


Name 

XtUnmanageChildren  —  remove  a  list  of  children  from  a  parent  widget's  managed  list. 

Synopsis 

void  XtUnmanageChildren (children,  num_children) 
WidgetList  children; 
Cardinal  num_children; 

Arguments 

children  Specifies  a  list  of  child  widgets. 

num_children       Specifies  the  number  of  children. 

Description 

XtUnmanageChildren  removes  a  list  of  widgets  from  a  parent  widget's  geometry  manage 
ment  list.  It  performs  the  following: 

•  Issues  an  error  if  children  do  not  all  have  the  same  parent  or  if  the  parent  is  not  a  sub 
class  of  compositeWidgetClass. 

•  Returns  immediately  if  the  common  parent  is  being  destroyed;  otherwise,  for  each  unique 
child  on  the  list,  XtUnmanageChildren  performs  the  following: 

Marks  children  visible  if  they  are  not  being  destroyed  and  are  currently  man 
aged.  For  each  visible  child,  if  the  child  is  realized,  it  makes  it  invisible  by  unmap- 
ping  it. 

If  the  parent  is  realized,  it  calls  the  change_managed  routine  of  the  widgets' 
parent  after  all  children  have  been  marked. 

XtUnmanageChildren  does  not  destroy  children.  Removing  widgets  from  a  parent's  man 
aged  set  is  often  a  temporary  banishment — some  time  later,  they  may  be  managed  again.  To 
destroy  widgets  entirely,  see  XtDestroyWidget. 

Note  that  XtManageChild,  XtManageChildren,  XtUnmanageChild,  and  Xt 
UnmanageChildren  are  low-level  routines  that  are  used  by  generic  composite  widget  build 
ing  routines.  In  addition,  composite  widgets  can  provide  widget-specific,  high-level  conve 
nience  procedures  to  let  applications  create  and  manage  children  more  easily. 

Structures 

typedef  Widget  *WidgetList; 

See  Also 

XtDestroyWidget(l),  XtIsManaged(l),  XtManageChild(\),  XtManageChildren(\),  XtUnmanageChild(\). 
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XtUnmapWidget  \ Yl 

v Xt  -  Widget  Lifecycle — 

Name 

XtUnmap Widget  —  unmap  a  widget  explicitly. 

Synopsis 

XtUnmapWidget ( w) 
Widget  w; 

Arguments 

w  Specifies  the  widget  to  be  unmapped. 

Description 

XtUnmapWidget  unmaps  a  widget's  window  from  its  display,  causing  it  to  become  invisible. 

Most  widgets  are  mapped  when  they  are  managed,  as  controlled  by  the  xtNmappedWhen- 
Managed  resource.  Widgets  that  are  not  mapped  must  be  mapped  explicitly  by  calling  xt- 
MapWidget.  XtUnmapWidget  takes  a  widget  off  the  display  without  deleting  it. 

See  Also 

XtManageChUd(\\  XtMapWidget(l),  XtSetMappedWhenManaged(\). 
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Jt  XtUnrealizeWidget 

—  Xt  -  Widget  Llfecycle ^ 

Name 

XtUnrealizeWidget  —  destroy  the  windows  associated  with  a  widget  and  its  descendants. 

Synopsis 

void  XtUnrealizeWidget (w) 
Widget  w; 

Arguments 

w  Specifies  the  widget 

Description 

XtUnrealizeWidget  destroys  the  windows  associated  with  a  widget  and  its  descendants. 

If  the  widget  is  currently  unrealized,  XtUnrealizeWidget  simply  returns;  otherwise,  it  per 
forms  the  following: 

•  Unmanages  the  widget  if  the  widget  is  managed. 

•  Makes  a  post-order  (child  to  parent)  traversal  of  the  widget  tree  rooted  at  the  specified 
widget  and,  for  each  widget  that  has  declared  a  callback  list  named  unrealize- 
Callback,  executes  the  procedures  on  the  XtNunrealizeCallback  list. 

•  Destroys  the  widget's  window  and  any  subwindows  by  calling  XDestroyWindow  on 
the  specified  widget's  window. 

Any  events  that  are  either  in  the  queue  or  that  arrive  following  a  call  to  XtUnrealize 
Widget  will  be  dispatched  as  if  the  window(s)  of  the  unrealized  widget(s)  had  never  existed. 

Note  that  this  call  simply  destroys  the  windows  associated  with  the  widget(s).  The  widget 
instances  themselves  remain  intact.  To  recreate  the  windows  at  a  later  time,  call  xt  Realize - 
Widget  again.  Compare  xtDestroyWidget,  which  destroys  the  widget(s)  themselves. 

If  the  widget  was  managed,  it  will  be  unmanaged  automatically  before  its  window  is  freed. 
See  Also 

XtDestroyWidget(\),  XtRealizeWidget(\). 
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XtVaAppCreateShell  \ 

v Xt  -  Initialization  — 

Name 

XtVaAppCreateShell  —  create  a  top-level  widget  that  is  the  root  of  a  widget  tree,  using  varargs 
argument  style. 

Synopsis 

Widget  XtVaAppCreateShell (application_name,  application_class, 

widget_class,  display,  .  .  .  ,  NULL) 
String  application_name; 
String  application_class; 
WidgetClass  widget_class; 
Display  *  display; 

Arguments 

app 1 icati on_name 

Specifies  the  name  of  the  application  instance. 

appl icati on_  class 

Specifies  the  class  name  of  this  application. 

widget_class    Specifies  the  widget  class  for  the  top-level  widget. 
display  Specifies  the  display. 

. . . ,  NULL  Specifies  the  NULL-terminated  variable-length  list  of  resource  name/value 

pairs  to  override  any  other  resource  specifications. 

Description 

XtVaAppCreateShell  is  identical  in  function  to  XtAppCreateShell  with  the  args 
and  num_args  arguments  replaced  by  a  varargs  list. 

See  Also 

XtAppCreateShell(\\  XtApplnitialize(\\  XtVaAppInitialize(l). 
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—Xt- Initialization 


J  XtVaApplnitialize 


Name 

XtVaApplnitialize  —  initialize  the  X  Toolkit  internals,  using  varargs  argument  style. 

Synopsis 

Widget  XtVaApplnitialize (app_context_return,  application_class,  options, 
num  options,  argc_in_out,  argv_in_out,  fallback_resources,  .  .  .  , 

NULL) 

XtAppContext  * app_ con text_re turn; 
String  application_class; 
XrmOptionDescList  options; 
Cardinal  num_options; 
Cardinal  * argc_in_out; 
String  *argv_in_out; 
String  * fallback_resources; 

Arguments 

app_context_return     Returns  the  application  context,  if  non-NULL. 

application_dass  Specifies  the  class  name  of  the  application. 

options  Specifies  the  command  line  options  table. 

num_opti  ons  Specifies  the  number  of  entries  in  options. 

argc_in_out  Specifies  a  pointer  to  the  number  of  command  line  arguments. 

argv_in_out  Specifies  the  command  line  arguments  array. 

fallback_resources     Specifies  resource  values  to  be  used  if  the  application  class  resource 

file  cannot  be  opened,  or  NULL. 

. . . ,  NULL  Specifies  the  NULL-terminated  variable-length  list  of  resource  name/value 

pairs  to  override  any  other  resource  specifications  for  the  created  shell. 

Description 

XtVaApplnitialize  initializes  the  Toolkit  internals,  creates  an  application  context,  opens 
and  initializes  a  display,  and  creates  the  initial  application  shell  instance  using  the  varargs  argu 
ment  style. 

XtVaApplnitialize  is  identical  in  function  to  xtApplnitialize  with  the  args  and 
num_args  arguments  replaced  by  a  varargs  list. 

See  Also 

XtApplnitialize  ( 1 ) 
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XtVaCreateArgsList 

v Xt  -  Memory  Allocation  — 

Name 

XtVaCreateArgsList  —  dynamically  allocate  a  varargs  list  for  use  with  the  xtVaNested- 
List  symbol  in  multiple  varargs  calls. 

Synopsis 

XtVarArgsList  XtVaCreateArgsList (unused,  .  .  . ,  NULL) 
XtPointer  unused; 

Arguments 

unused  This  argument  is  not  currently  used  and  must  be  specified  as  NULL. 

. . . ,  NULL  Specifies  the  NULL-terminated  variable-length  list  of  resource  name/value 

pairs  to  override  any  other  resource  specifications. 

Description 

XtVaCreateArgsList  allocates  memory  and  copies  its  arguments  into  a  single  list  pointer 
that  may  be  used  with  XtVaNestedList.  The  end  of  both  lists  is  identified  by  a  name  entry 
containing  NULL.  Any  entries  of  type  xtVaTypedArg  are  copied  as  specified  without  apply 
ing  conversions.  Data  passed  by  reference  (including  strings)  is  not  copied,  only  the  pointers 
themselves;  the  caller  must  ensure  that  the  data  remains  valid  for  the  lifetime  of  the  created 
varargs  list.  When  no  longer  needed,  the  list  should  be  freed  using  xtFree. 

To  permit  modification  without  recompilation,  use  of  resource  files  and  the  resource  database  is 
generally  encouraged  over  lengthy  ArgList  or  varargs  lists  whenever  possible. 

Structures 

typedef  XtPointer  XtVarArgsList; 

See  Also 

XtCalloc(\\  XtFree(l),  XtMalloc(\\  XtMergeArgLists(l\  XWew(l),  XtNewStringV),  XtRealloc(l),  Xt- 
SetArgd). 
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J  XtVaCreateManagedWidget 

— Xt  -  Widget  Llfecycle ' 

Name 

XtVaCreateManagedWidget  —  create  and  manage  a  child  widget  in  a  single  procedure,  using 

varargs  argument  style. 

Synopsis 

Widget  XtVaCreateManagedWidget (name,  widget_class,  parent,  .  .  .  ,  NULL) 
String  name; 

WidgetClass  widget_class; 
Widget  parent; 

Arguments 

name  Specifies  the  text  name  for  the  created  widget. 

widget_dass    Specifies  the  widget  class  pointer  for  the  created  widget. 
parent  Specifies  the  parent  widget 

. . . ,  NULL  Specifies  the  NULL-terminated  variable-length  list  of  resource  name/value 

pairs  to  override  any  other  resource  specifications. 

Description 

XtVaCreateManagedWidget  is  identical   in  function  to  XtCreateManagedWidget 
with  the  args  and  num_args  arguments  replaced  by  a  varargs  list. 

See  Also 

XtCreoteWidget(l),  XtCreateMonagedWidget(\),  XtDestroyWidget(l),  XtManageChild(l),  XtManage- 
CHUdren(l),  XtVaCreateWidget(\). 
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XtVaCreatePopupShell  \ 

Xt  -  Pop  Ups— 

Name 

XtVaCreatePopupShell  —  create  a  pop-up  shell,  using  varargs  argument  style. 

Synopsis 

Widget  XtVaCreatePopupShell (name,  widget_class,  parent,  .  .  .  ,  NULL) 
String  name; 

WidgetClass  widget_class; 
Widget  parent; 

Arguments 

name  Specifies  the  text  name  for  the  created  shell  widget 

widget _ class    Specifies  the  widget  class  pointer  for  the  created  shell  widget. 
parent  Specifies  the  parent  widget 

. . . ,  NULL  Specifies  the  NULL-terminated  variable-length  list  of  resource  name/value 

pairs  to  override  any  other  resource  specifications. 

Description 

XtVaCreatePopupShell  is  identical  in  function  to  XtCreatePopupShell  with  the 
args  and  num_args  arguments  replaced  by  a  varargs  list. 

See  Also 

XtCollbackExclusive(l),  XtCallbackNone(\),  XtCallbackNonexclusive(\),  XtCallbackPopdown(\\  Xt- 
CreatePopupShell(\\  XtMenuPopdown,(l)  XtMenuPopup,(\)  XtPopdown(\\  XtPopup(\),  XtPopup- 
SpringLoaded(\). 
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—  Xt- Widget  L if ecycle- 


J.  XtVaCreateWidget 


Name 

XtVaCreateWidget  —  create  an  instance  of  a  widget  using  varargs  argument  style. 

Synopsis 

Widget  XtVaCreateWidget (name,  object_class,  parent,   .  .  .  ,  NULL) 
String  name; 

WidgetClass  object_class; 
Widget  parent; 

Arguments 

name  Specifies  the  resource  name  for  the  created  widget. 

ojbject_class    Specifies  the  widget  class  pointer  for  the  created  object;  may  be  of  class 
objectClass  or  any  subclass  thereof. 

parent  Specifies  the  parent  widget 

. . . ,  NULL  Specifies  the  NULL-terminated  variable-length  list  of  resource  name/value 

pairs  to  override  any  other  resource  specifications. 

Description 

XtVaCreateWidget  is  identical  in  function  to  XtCreateWidget  with  the  args  and 
num_args  arguments  replaced  by  a  varargs  list. 

See  Also 

XtCreateManagedWidget(\ ),  XtVaCreateWidget(\ ),  XtVaCreateManagedWldget (1 ). 
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XtVaGetAppMcationResources 

v Xt  -  Resource  Management — 

Name 

XtVaGetApplicationResources  —  retrieve  resources  for  the  overall  application  using  varargs 

argument  style. 

Synopsis 

void  XtVaGetApplicationResources (object,  base,  resources,  num  resources, 

.  .  .  ,  NULL) 
Widget  object; 
XtPointer  base; 
XtResourceList  resources; 
Cardinal  num_resources; 

Arguments 

object  Specifies  the  object  that  identifies  the  resource  database  to  search  (the  data 

base  is  that  associated  with  the  display  for  this  object);  may  be  of  class  Object 
or  any  subclass  thereof. 

base  Specifies  the  base  address  of  the  subpart  data  structure  into  which  the 

resources  will  be  written. 

resources          Specifies  the  resource  list  for  the  subpart. 
nu/n_resources  Specifies  the  number  of  resources  in  the  resource  list. 

....  NULL  Specifies  the  NULL-terminated  variable-length  list  of  resource  name/value 

pairs  to  override  any  other  resource  specifications. 

Description 

XtVaGetApplicationResources  is  identical  in  function  to  XtGetApplication- 
Re sources  with  the  args  and  num_args  arguments  replaced  by  a  varargs  list. 

See  Also 

XtGetSubresources(l\  XtOffset(l),  XtOffsetOf(\). 


358  X  Toolkit  Intrinsics  Reference  Manual 


-Xt-  Resource  Management /  XtVaGetSubreSOUrCeS 

Name 

XtVaGetSubresources  —  fetch  resources  for  widget  subparts,  using  varargs  argument  style. 

Synopsis 

void  XtVaGetSubresources (object,  base,  name,  class,  resources, 

num_re sources,  .  .  .  ,  NULL) 
Widget  object; 
XtPointer  base; 
String  name; 
String  class; 
XtResourceList  resources; 
Cardinal  nu/n_resources; 

Arguments 

object  Specifies  the  object  used  to  qualify  the  subpart  resource  name  and  class;  may 

be  of  class  Object  or  any  subclass  thereof. 

base  Specifies  the  base  address  of  the  subpart  data  structure  into  which  the 

resources  will  be  written. 

name  Specifies  the  name  of  the  subpart. 

class  Specifies  the  class  of  the  subpart. 

resources          Specifies  the  resource  list  for  the  subpart. 
/iu/n_resources  Specifies  the  number  of  resources  in  the  resource  list. 

. . . ,  NULL  Specifies  the  NULL-terminated  variable-length  list  of  resource  name/value 

pairs  to  override  any  other  resource  specifications. 

Description 

XtVaGetSubresources  is  identical  in  function  toXtGetSubresources  with  the  args 
and  num_args  arguments  replaced  by  a  varargs  list. 

See  Also 

XtGetApplicotionResources  ( 1 ),  XtGetSubresources  ( 1 ). 
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XtVaGetSubvalues  \ v< 

v Xt  -  Resource  Management — 

Name 

XtVaGetSubvalues  —  retrieve  the  current  values  of  nonwidget  resources  associated  with  a 
widget  instance,  using  varargs  argument  style. 

Synopsis 

void   XtVaGetSubvalues  (base,    resources,    nu/n_resources,      .  .  .  ,    NULL) 
XtPointer   base; 
XtResourceList    resources; 
Cardinal   nu/n_resources; 

Arguments 

base  Specifies  the  base  address  of  the  subpart  data  structure  for  which  the 

resources  should  be  retrieved. 

resources          Specifies  the  nonwidget  resource  list. 
/]u/n_resources  Specifies  the  number  of  resources  in  the  resource  list. 

. . . ,  NULL  Specifies  the  NULL-terminated  variable-length  .list  of  resource  name/value 

pairs  to  override  any  other  resource  specifications,  values  are  to  be  stored. 
The  arguments  and  values  are  dependent  on  the  subpart. 

Description 

XtVaGetSubvalues  is  identical  in  function  to  XtGetSubvalues  with  the  args  and 
num_args  arguments  replaced  by  a  varargs  list.  XtVaTypedArg  is  not  supported  for  Xt 
VaGetSubvalues.  If  xtVaTypedArg  is  specified  in  the  list,  a  warning  message  is  issued 
and  the  entry  is  then  ignored. 

See  Also 

XtGetSubvalues(l\  XtSetArgd). 
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-Xt -  Resource  Management /  XtVaGetValUeS 

Name 

XtVaGet Values  —  retrieve  the  current  values  of  resources  associated  with  a  widget  instance, 
using  varargs  argument  style. 

Synopsis 

void  XtVaGetValues( object,  .  .  .  ,  NULL) 
Widget  object; 

Arguments 

object  Specifies  the  object  whose  resource  values  are  to  be  returned;  may  be  of  class 

Object  or  any  subclass  thereof. 

....  NULL  Specifies  the  NULL-terminated  variable-length  list  of  resource  name/value 

pairs  to  override  any  other  resource  specifications. 

Description 

XtVaGetValues  is  identical  in  function  to  XtGetValues  with  the  args  and  num__args 
arguments  replaced  by  a  varargs  list.  All  value  entries  in  the  list  must  specify  pointers  to  stor 
age  allocated  by  the  caller  to  which  the  resource  value  will  be  copied.  It  is  the  caller's  respon 
sibility  to  ensure  that  sufficient  storage  is  allocated.  If  xtVaTypedArg  is  specified,  the  type 
field  specifies  the  representation  desired  by  the  caller  and  the  size  field  specifies  the  number  of 
bytes  allocated  to  store  the  result  of  the  conversion.  If  the  size  is  insufficient,  a  warning  mes 
sage  is  issued  and  the  list  entry  is  skipped. 

See  Also 

XtGetValues(\\  XtSetArgd),  XtSetValues(l),  XtVaSetValues(l). 
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XtVaSetSubvalues 

•Xt  -  Resource  Management- 
Name 

XtVaSetSubvalues  —  set  the  current  values  of  nonwidget  resources  associated  with  a  widget 
instance,  using  varargs  argument  style. 

Synopsis 

void  XtVaSetSubvalues  (base,    resources,    nu/n_resources,      .  .  .  ,    NULL) 
XtPointer   base; 
XtResourceList    resources; 
Cardinal   /}um_resources; 

Arguments 

base  Specifies  the  base  address  of  the  subpart  data  structure  into  which  the 

resources  should  be  written. 

resources          Specifies  the  nonwidget  resource  list. 
nu/n_resources  Specifies  the  number  of  resources  in  the  resource  list. 

. . . ,  NULL  Specifies  the  NULL-tenninated  variable-length  list  of  resource  name/value 

pairs  to  override  any  other  resource  specifications.  The  resources  and  values 
passed  are  dependent  on  the  subpart  of  the  widget  being  modified. 

Description 

XtVaSetSubvalues  is  identical  in  function  to  XtSetSubvalues  with  the  args  and 
num_args  arguments  replaced  by  a  varargs  list.  XtVaTypedArg  is  not  supported  for  Xt 
VaSetSubvalues.  If  xtVaTypedArg  is  specified  in  the  list,  a  warning  message  is  issued 
and  the  entry  is  then  ignored. 

See  Also 

XtSetArg(l\ 

set  volues(4).  . ' 


362  X  Toolkit  Intrinsics  Reference  Manual 


— Xt  -  Resource  Management- 


XtVaSetValues 


Name 

XtVaSetValues  —  modify  the  current  resource  values  associated  with  a  widget  instance,  using 
varargs  argument  style. 


Synopsis 

void   XtVaSetValues (object, 
Widget    object; 


NULL) 


Arguments 

object 
....NULL 


Specifies  the  object  whose  resources  are  to  be  modified;  may  be  of  class 
Object  or  any  subclass  thereof. 

Specifies  the  NULL -terminated  variable-length  list  of  resource  name/value 
pairs  to  override  any  other  resource  specifications.  The  resources  and  values 
passed  are  dependent  on  the  widget  being  modified. 


Description 

XtVaSetValues  is  identical  in  function  to  XtSetValues  with  the  args  and  num_args 
arguments  replaced  by  a  varargs  list. 

See  Also 

XtSetArg(\\ 

set_volues(4),  set_values_hook(4). 
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XtWarning  \ 

v Xt  -  Error  Handling  — 

Name 

XtWaming  —  call  the  installed  low-level  warning  handler. 

Synopsis 

void  XtWarning (message) 
String  message; 

Arguments 

message  Specifies  the  nonfatal  error  message  to  be  reported. 

Description 

XtWarning  has  been  superseded  by  xtAppWarning.  XtWarning  calls  the  existing  low- 
level  warning  handler.  Warnings  are  nonfatal.  The  default  low-level  warning  handler  provided 
by  the  Intrinsics  is  _XtWarning.  On  POSIX-based  systems,  it  prints  the  message  to  standard 
error  and  returns  to  the  caller. 

Most  programs  should  use  the  more  elaborate  XtWarningMsg,  to  print  customized  error  mes 
sages  from  an  error  database.  XtWarningMsg  allows  an  application  to  be  more  easily  cus 
tomized  by  site,  and  allows  for  international  considerations  in  reporting  errors. 

A  custom  warning  handler  can  be  installed  by  calling  XtSetWarningHandler. 
See  Also 

XtSetWarningHandler  (\\  XtSetWarningMsgHandler(\),  XtWarningMsg  (I), 
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— Xt-  Error  Handling 


XtWarningMsg 


Name 

XtWarningMsg  —  call  the  installed  high-level  warning  handler. 

Synopsis 

void  XtWarningMsg (name,  type,  class,  default,  params,  num_params) 
String  name; 
String  type; 
String  class; 
String  default; 
String  *params; 
Cardinal  *num  params; 


Arguments 

name 

type 

class 

default 

params 

num  params 


Specifies  the  general  kind  of  error. 

Specifies  the  detailed  name  of  the  error. 

Specifies  the  resource  class. 

Specifies  the  default  message  to  use. 

Specifies  a  pointer  to  a  list  of  values  to  be  stored  in  the  message. 

Specifies  the  number  of  values  in  the  parameter  list. 


Description 

XtWarningMsg  has  been  superseded  by  XtAppWarningMsg.  XtWarningMsg  calls  the 
currently  installed  high-level  warning  handler.  This  is  the  preferred  method  of  delivering  warn 
ing  messages.  The  warning  handler  that  gets  invoked  can  manage  details  like  international 
considerations  and  system -wide  error  logging. 

Warnings  are  non-fatal  and  assumed  to  be  informative. 

The  Intrinsics  internal  errors  all  have  class  XtToolkitError. 

See  Also 

XtSetWarningHandler(l),  XtSetWarningMsgHandIer(l),  XtWarningd). 
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XtWidgetToApplicationContext      v^ 


•Xt  -  Application  Context — 


Name 

XtWidgetToApplicationContext  —  get  the  application  context  for  a  given  widget. 

Synopsis 

XtAppContext  XtWidgetToApplicationContext (object) 
Widget  object; 

Arguments 

object  Specifies  the  object  for  which  you  want  the  application  context;  may  be  of 

class  Object  or  any  subclass  thereof. 

Description 

XtWidgetToApplicationContext  returns  the  application  context  for  the  specified 
widget. 

It  locates  the  application  context  by  following  the  chain  of  Core  widget  parent  structures 
until  it  finds  one  that  is  a  subclass  of  the  fundamental  widget  class  windowOb  jClass.  Then 
it  accesses  the  application  context  associated  with  the  display  for  that  widget. 

This  function  is  useful  for  calling  "XtApp"  functions  from  widget  code. 
See  Also 

XtCreateApplicationContext  ( 1 ) 
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Name 

XtWindow  —  return  the  window  of  the  specified  widget. 

Synopsis 

Window  XtWindow ( w) 
Widget  w, 

Arguments 

w  Specifies  the  widget 

Description 

XtWindow  returns  the  window  of  the  specified  widget  Note  that  the  window  is  obtained  from 
the  Core  window  field,  which  may  be  NULL  if  the  widget  has  not  yet  been  realized. 

See  Also 

XtWindawToWidget(\) 
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XtWindowOfObject  \ Xl  _  Objec,  lnlormatlon_ 

Name 

XtWindowOfObject  —  return  the  window  for  the  nearest  ancestor  of  object  that  is  of  class 
Core. 

Synopsis 

Window  XtWindowOfObject (object) 
Widget  object; 

Arguments 

object  Specifies  the  object;  it  may  be  of  class  Object  or  any  subclass  thereof. 

Description 

XtWindowOfObject  is  identical  in  function  to  Xtwindow  if  object  is  a  widget;  other 
wise  XtWindowOfObject  returns  the  window  for  the  nearest  ancestor  of  object  that  is  of 
class  Core. 

See  Also 

XtDisplayOJObject(l),XtScreenOjObject(l). 
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— Xt  -  Object  Information- 


J  XtWindowToWidget 


Name 

XtWindowToWidget  —  translate  a  window  and  display  pointer  into  a  widget  ID. 

Synopsis 

Widget  XtWindowToWidget (display,  window) 
Display  *  display; 
Window  window; 

Arguments 

display  Specifies  the  display  on  which  the  window  is  defined. 

window  Specify  the  window  for  which  you  want  the  widget 

Description 

XtWindowToWidget  takes  a  display  pointer  and  a  window  and  returns  the  associated  widget 
ID.  The  widget  must  be  within  the  same  application  as  the  caller. 

On  failure,  XtWindowToWidget  returns  NULL. 
See  Also 

XtNomeToWidget(\\  XtWiruiow(l). 
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Section  2 


Prototype  Procedures 


This  section  contains  alphabetically-organized  reference  pages  for  each 
function  type  (typedef)  that  can  be  registered  by  the  functions  in  Section  1. 
In  C  parlance  these  are  sometimes  called  prototype  procedures. 

Each  page  contains  a  synopsis  of  the  function's  calling  sequence,  its  argu 
ments,  a  description  of  its  purpose  and  features,  and  a  reference  to  related 
routines,  prototype  procedures,  and  methods. 

In  This  Section: 


XtActionHookProc 

XtActionProc 

XtCallbackProc 

XtCancelConvertSelection  Proc 

XtCaseProc 

XtConvertArg  Proc 

XtConverter 

XtConvertSelection  IncrProc 

XtConvertSelection  Proc 

XtDestructor 

XtErrorHandler 

XtErrorMsg  Handler 

XtEventHandler 


XtFilePredicate 

XtlnputCallbackProc 

XtKeyProc 

XtLoseSelection  IncrProc 

XtLoseSelection  Proc 

XtOrderProc 

XtResourceDefaultProc 

XtSelectionCallbackProc 

XtSelectionDonelncrProc 

XtSelectionDoneProc 

XtTimerCallbackProc 

XtTypeConverter 

XtWorkProc 


-Xt-*ans,a«onsand  Actions '  XtACtiOnHOOkPfOC 

Name 

XtActionHookProc  —  prototype  action  hook  procedure. 

Synopsis 

typedef   void    ( *XtActionHookProc) (Widget,    XtPointer,    String,    XEvent*, 

String*,    Cardinal*) 
Widget    w; 

XtPointer    client_data; 
String   action_name; 
XEvent*    event; 
String*   params; 
Cardinal*    num_params; 


Arguments 

w 

client   data 


Specifies  the  widget  whose  action  is  about  to  be  dispatched. 

Specifies  the  application-specific  closure  that  was  passed  to  xtAppAdd- 
ActionHook. 

Specifies  the  name  of  the  action  to  be  dispatched. 
Specifies  the  event  argument  that  will  be  passed  to  the  action  routine. 
Specifies  the  action  parameters  that  will  be  passed  to  the  action  routine. 
Specifies  the  count  of  entries  in  params. 


action_name 
event 
params 
num_params 

Description 

An  application  can  specify  a  procedure  that  will  be  called  just  before  every  action  routine  is 
dispatched  by  the  translation  manager.  To  do  so,  the  application  supplies  a  procedure  pointer  of 
type  XtActionHookProc.  Action  hooks  should  not  modify  any  of  the  data  pointed  to  by  the 
arguments  other  than  the  client_data  argument 

One  use  of  an  XtActionHookProc  is  to  record  the  arguments  passed  to  each  action  so  that 
user  actions  are  recorded  for  later  playback  using  xtCallActionProc.  This  is  one  way  to 
implement  keyboard  macros. 

See  Also 

XtAppAddActlonHook(\\  XtCallActionProc (1),  XtRemoveActionHook(l). 
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XtActionProc  v xt  _  Translations  and  Actions_ 

Name 

XtActionProc  —  prototype  action  procedure. 

Synopsis 

typedef  void  ( *XtActionProc) (Widget,  XEvent  *,  String  *,  Cardinal  *); 
Widget  w; 
XEvent  *event; 
String  *params; 
Cardinal  *num_params; 

Arguments 

w  Specifies  the  widget  that  caused  the  action  to  be  called. 

event  Specifies  the  event  that  caused  the  action  to  be  called.  If  the  action  is  called 

after  a  sequence  of  events,  then  the  last  event  in  the  sequence  is  used. 

pa  rams  Specifies  a  pointer  to  the  list  of  strings  that  were  specified  in  the  translation 

table  as  arguments  to  the  action. 

num_params        Specifies  the  number  of  arguments  specified  in  the  translation  table. 

Description 

A  widget  class  record  can  contain  an  action  table.  In  addition,  using  xtAppAddActions,  an 
application  can  register  its  own  action  tables  with  the  Resource  Manager.  An  action  table  con 
sists  of  a  list  of  string  names  (which  can  be  used  in  translation  tables  to  associate  an  action  with 
one  or  more  events)  and  corresponding  function  pointers  (often  spelled  the  same  as  the  string). 
The  function  pointer  is  of  type  XtActionProc. 

An  action  is  a  function  with  four  arguments:  a  widget,  an  event,  a  string  containing  any  argu 
ments  specified  for  the  action,  and  the  number  of  arguments  contained  in  the  string.  In  most 
cases,  the  last  two  arguments  are  unused.  When  you  don't  use  the  last  two  arguments,  be  sure 
to  place  the  lint  comment  /*ARGSUSED*/  just  before  the  action  function  definition.  To  con 
form  to  ANSI  C  standards,  all  four  arguments  of  an  action  should  be  declared,  even  if  the  trail 
ing  arguments  are  not  used. 

One  major  difference  between  an  action  function  and  a  callback  function  is  that  action  func 
tions  are  called  with  an  event  as  an  argument,  whereas  actions  do  not  have  the  client_data 
or  call_data  arguments  present  for  callback  functions.  This  means  the  only  way  to  pass 
application  data  into  an  action  function  is  through  global  variables.  On  the  other  hand,  the 
presence  of  the  event  argument  means  that  you  can  use  the  contents  of  the  event  structure  in  the 
action  function. 

Many  action  routines  are  intentionally  written  not  to  depend  on  the  detailed  information  inside 
any  particular  type  of  event,  so  that  the  user  uses  the  translation  table  to  call  the  action  in 
response  to  different  types  of  events.  For  example,  it  is  useful  for  an  action  routine  normally 
triggered  by  a  pointer  click  to  work  when  called  in  response  to  a  key  instead.  Such  an  action 
should  not  depend  on  the  event  structure  fields  unique  to  button  events. 
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However,  many  other  action  routines,  and  most  event  handlers,  do  use  the  detailed  information 
inside  event  structures.  The  first  member  of  the  event  structure,  type,  identifies  the  type  of 
event  this  structure  represents,  and  hence  implies  what  other  fields  are  present  in  the  structure. 

To  access  event  structure  fields  other  than  type,  you  need  to  cast  XEvent  into  the  appropriate 
event  structure  type.  If  you  are  expecting  only  one  type  of  event  to  trigger  this  action,  then  you 
can  simply  print  an  error  or  warning  message  when  an  illegal  event  triggers  it. 

static  void 
Turn (w,  tevent) 
Widget  w; 
XEvent  * tevent; 
{ 

XButtonEvent  *event  =  (XButtonEvent  *)  tevent; 

TetrisWidget  tw  =  {TetrisWidget)  w; 

/*  we  must  now  use  only  the  fields  in  XButtonEvent  */ 

if  (event->type  !=  ButtonPress) 

XtWarning ("TetrisWidget :  Turn  action  invoked\ 
by  wrong  event  type."); 
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XtCallbackProc  \ 


Xt  -  Callbacks- 


Name 

XtCallbackProc  —  prototype  callback  procedure. 

Synopsis 

typedef  void  (*XtCallbackProc) (Widget,  XtPointer,  XtPointer); 
Widget  w; 

XtPointer  client_data; 
XtPointer  call_data; 

Arguments 

w  Specifies  the  widget  for  which  the  callback  is  registered. 

client_data      Specifies  the  data  that  the  widget  will  pass  to  the  client's  procedure  when  the 
widget  performs  the  callback. 

ca ll_data          Specifies  the  data  registered  with  the  callback  by  the  client. 

Description 

Generally  speaking,  a  widget  expecting  to  interact  with  an  application  will  declare  one  or  more 
callback  lists  as  resources;  the  application  adds  functions  to  these  callback  lists,  and  then  these 
functions  will  be  invoked  whenever  the  predefined  callback  conditions  are  met.  Because  call 
back  lists  are  resources,  the  application  can  set  or  change  at  any  time  the  function  or  functions 
that  will  be  invoked. 

Callbacks  are  not  necessarily  invoked  in  response  to  any  event;  a  widget  can  call  the  specified 
routines  at  any  arbitrary  point  in  its  code,  whenever  it  wants  to  provide  a  "hook"  for  application 
interaction.  For  example,  all  widgets  provide  an  XtNdestroyCallback  resource  to  allow 
applications  to  interpose  a  routine  to  be  executed  when  the  widget  is  destroyed. 

Whenever  a  client  wants  to  pass  a  callback  list  as  an  argument  in  an  XtCreateWidget,  xt- 
SetValues,  or  xtGetValues  call,  it  should  specify  the  address  of  a  NULL-terminated  array 
of  type  xtCallbackList  (see  the  Structures  section  below).  Callback 'procedure  fields  for 
use  in  callback  lists  are  of  type  XtCallbackProc. 

When  a  callback  procedure,  or  list  of  callback  procedures,  is  passed  as  a  resource  argument,  Xt 
constructs  an  internal  data  structure  for  the  callback  list.  Subsequently,  callback  lists  cannot  be 
queried.  Because  Xt  doesn't  support  a  string-to-callback  resource  converter,  callbacks  cannot 
be  specified  in  resource  files.  The  internal  form  can  only  be  accessed  by  the  Intrinsics  functions 
XtAddCallback,  XtAddCallbacks,  XtRemoveCallback,  XtRemoveCallbacks, 
XtCallCallbacks,  etc.  Furthermore,  since  callback  lists  are  handled  specifically  by  the 
Intrinsics,  widget  procedures  should  not  allocate  memory  for  callback  lists  passed  as  resources. 
Unlike  other  resources,  a  widget's  initialize  method  should  not  attempt  to  make  copies  of 
resources  of  type  XtRCallback. 
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Xt-  Callbacks  (continued)  XtCallbackProc 

An  XtCallbackProc  takes  three  arguments: 

•  The  first  argument  is  the  widget  that  triggered  the  callback,  as  specified  as  the  first  argu 
ment  in  xtAddCallback.  You  would  use  the  value  of  this  argument  in  your  callback 
function  if  you  registered  the  same  function  as  a  callback  for  two  different  widgets,  and 
if  you  wanted  to  distinguish  in  the  callback  which  widget  called  it. 

•  The  second  argument,  die/Jt_data,  is  the  value  passed  as  the  last  argument  of  Xt 
AddCallback.   client_data  provides  a  way  for  the  client  registering  the  callback 
also  to  register  client-specific  data  (for  example,  a  pointer  to  additional  information 
about  the  widget,  a  reason  for  invoking  the  callback,  and  so  on).  clie/it_data  should 
be  NULL  if  all  necessary  information  is  in  the  widget 

The  third  argument,  call_data,  is  a  piece  of  data  passed  from  the  widget.  Some 
classes  of  widget  set  this  argument,  but  others  do  not.  The  documentation  for  the  widget 
will  specify  the  contents  of  this  data  if  it  is  used.  The  Athena  Command  widget  doesn't 
provide  any  call_data,  but  the  Athena  Scroll  widget,  for  example,  passes  back  the 
current  position  of  the  thumb. 

The  call_data  argument  is  a  convenience  to  avoid  having  simple  cases  where  the  client 
would  otherwise  have  to  call  xt  Get  Values  or  a  widget-specific  function  to  retrieve  data 
from  the  widget.  Widgets  should  generally  avoid  putting  complex  state  information  in 
call_data.  The  client  can  use  the  more  general  data  retrieval  methods,  if  necessary. 

For  the  Intrinsics  to  find  and  correctly  handle  callback  lists,  they  must  be  declared  with  a 
resource  type  of  XtRCallback.  The  internal  representation  of  a  callback  list  is  implementa 
tion-dependent;  widgets  may  make  no  assumptions  about  the  value  stored  in  this  resource  if  it 
is  non-NULL.  Except  to  compare  the  value  to  NULL  (which  is  equivalent  to  xtCallbackHas- 
None  returned  by  xtHasCallbacks),  access  to  callback  list  resources  must  be  made 
through  other  Intrinsics  procedures. 

Structures 

typedef   struct    { 

XtCallbackProc  callback; 

caddr_t   closure; 
}    XtCallbackRec,    *XtCallbackList; 

For  example,  the  callback  list  for  procedures  A  and  B  with  client  data  clientDataA  and 
clientDataB,  respectively,  is: 

static  XtCallbackRec  callbacks!]  =  { 

{A,  (caddr_t)  clientDataA}, 

{B,  (caddr_t)  clientDataB}, 

{ (XtCallbackProc)  NULL,  (caddr_t)  NULL} 
}; 

See  Also 

XtAddCollbockd),  XtAddCollbocks(\\  XtCollCallbacks(\\  XtCreateWidget(l),  XtGetValues(l),  XtHas- 
Callbacks(\),  XtRemoveCallback(l)t  XtRemoveCallbacks(\),  XtSetValues(l),  XtVaGetValues(l),  XtVa- 
SetValues(l). 
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XtCancelConvertSelectionProc    \ 


Xt-  Selections— 


Name 

XtCancelConvertSelectionProc  —  prototype  procedure  to  cancel  incremental  selection 

transfer. 

Synopsis 

typedef  void  ( *XtCancelConvertSelectionProc)  (Widget,  Atom*,  Atom*,  Xt- 

Requestld*,  XtPointer) 
Widget  w; 
Atom  *selection; 
Atom  *  target; 
XtRequestld  * request_id; 
XtPointer  client_data; 

Arguments 

w  Specifies  the  widget  that  owns  the  selection. 

selection          Specifies  the  atom  that  names  the  selection  being  transferred. 
target  Specifies  the  target  type  to  which  the  conversion  was  done. 

request_i  d       Specifies  an  opaque  identification  for  a  specific  request. 

client_data      Specifies  the  value  passed  in  by  the  widget  when  it  took  ownership  of  the 
selection. 

Description 

This  procedure  is  registered  in  a  call  to  xtOwnSelectionlncremental,  and  is  called  by 
the  Intrinsics  when  (as  determined  by  the  selection  timeout  or  other  mechanism)  any  remaining 
segments  of  the  selection  no  longer  need  to  be  transferred.  Upon  receiving  this  callback,  the 
selection  request  is  considered  complete  and  the  owner  can  free  the  memory  and  any  other 

resources  that  have  been  allocated  for  the  transfer. 

« 

See  Also 

XtGetSelectionVolueIncremental(\),  XtGetSelectionValuesIncremental(l\  XtGetS  election! imeout(\),  Xt- 

OwnSelectionIncremental(\),  XtSetSelectionTimeout(\ ), 

XtConvertSelectionlncrProc (2),  XtLoseSelectionlncrProc (2),  XtSelectionDonelncrProc  (2). 
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/  XtCaseProc 

— Xt- Keyboard  Handling ' 

Name 

XtCaseProc  —  prototype  procedure  called  to  convert  the  case  of  keysyms. 

Synopsis 

typedef  void  ( *XtCaseProc)  (Display*,  KeySym,  KeySym  *,  KeySym  *); 
Display  *  display 
KeySym   keysym; 
KeySym   * lower_return; 
KeySym   *upper_return; 

Arguments 

display  Provides  the  display  connection  for  which  the  conversion  is  required. 

keysym  Specifies  the  keysym  to  convert. 

1  o wer_ret  urn         Specifies  the  lower-case  equivalent  for  the  keysym. 

upper_return         Specifies  the  upper-case  equivalent  for  the  keysym. 

Description 

To  handle  capitalization  of  nonstandard  keysyms,  the  Intrinsics  allow  clients  to  register  case 
conversion  routines.  Case  converter  procedure  pointers  are  of  type  XtCaseProc.  The  case 
converter  can  be  registered  with  xtRegisterCaseConverter. 

An  XtCaseProc  allows  an  application  to  specify  its  own  upper-case  and  lower-case  transla 
tions  for  keyboard  keys. 

If  there  is  no  case  distinction,  the  procedure  should  store  the  input  keysym  into  both  return  val 
ues. 

Examples 

Here  is  the  default  case  converter  from  the  R4  Intrinsics: 

/*  ARGSUSED  */ 

void  _XtConvertCase (dpy,  sym,  lower,  upper) 
Display  *dpy; 
KeySym  sym; 
KeySym  * lower; 
KeySym  *upper; 
{ 

*  lower  =  sym; 
*upper  =  sym; 
switch (sym  »  8)  { 
case  0 : 

if  ((sym  >=  XK_A)  &&  (sym  <=  XK_Z) ) 

*lower  +=  (XK_a  -  XK_A) ; 
else  if  ((sym  >=  XK_a)  &&  (sym  <=  XK_z) ) 

*upper  -=  (XK_a  -  XK_A) ; 
else  if  ((sym  >=  XK_Agrave)  &&  (sym  <=  XK_Odiaeresis) ) 

*  lower  +=  (XK_agrave  -  XK_Agrave) ; 

else  if  ((sym  >=  XK_agrave)  &&  (sym  <=  XK_odiaeresis) ) 
*upper  -=  (XK  agrave  -  XK_Agrave) ; 
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else  if  ((sym  >=  XK_Ooblique)  &&  (sym  <=  XK_Thorn)  ) 

*lower  +=  (XK_oslash  -  XK_Ooblique)  ; 

else  if  (  (sym  >=  XK_oslash)  &&  (sym  <=  XK_thorn)  ) 

*upper  -=  (XK_oslash  -  XK_Ooblique)  ; 
break; 
default  : 

/*  XXX  do  all  other  sets  */ 
break; 


Changing  the  keyboard  mapping  is  discussed  in  Chapter  13,  Miscellaneous  Toolkit  Program 
ming  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 

See  Also 

XtConvertCase(\),  XtGetKeysymTable(\\  XtKeysymToKeycodeList(\\  XtRegisterCaseConverter(\),  Xt- 
SetKeyTranslator  (  1  ),  XfTranslateKeycode  (  1  ). 
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j  XtConvertArgProc 

— Xt  -  Resource  Management ' 

Name 

XtConvertArgProc  —  prototype  procedure  for  argument  conversion. 

Synopsis 

typedef  void  (*XtConvertArgProc) (Widget,  Cardinal  *,  XrmValue  *) 
Widget  object; 
Cardinal  *size; 
XrmValue  *  value; 

Arguments 

object  Passes  the  object  for  which  the  resource  is  being  converted,  or  passes  NULL  if 

the    converter    was    invoked    by    xtCallConverter    or   xtoirect- 
Convert. 

size  Passes  a  pointer  to  the  size  field  from  the  XtConvertArgRec  structure. 

value  Passes  a  pointer  to  a  descriptor  into  which  the  procedure  must  store  the  con 

version  argument 

Description 

XtConvertArgProc  gets  an  argument  needed  when  calling  a  converter.  It  is  registered  in 
an  XtConvertArgRec  structure  with  the  symbol  xtProcedureArg.  When  invoked,  the 
XtConvertArgProc  procedure  must  derive  a  conversion  argument  and  store  the  address  and 
size  of  the  argument  in  its  val  ue  argument 

To  permit  re-entry,  XtConvertArgProc  should  return  the  address  of  storage  whose  lifetime 
is  no  shorter  than  the  lifetime  of  object.  If  object  is  NULL,  the  lifetime  of  the  conversion 
argument  must  be  no  shorter  than  the  lifetime  of  the  resource  with  which  the  conversion  argu 
ment  is  associated.  The  Intrinsics  do  not  guarantee  to  copy  this  storage,  but  they  do  guarantee 
not  to  reference  it  if  the  resource  is  removed  from  the  conversion  cache. 

Examples 

Here  is  how  the  XtRString-to-XtRCursor  converter  would  be  registered  if  it  were  not 
already  registered  by  Xt: 

/*ARGSUSED*/ 

static  void  FetchDisplayArg (widget,  size,  value) 

Widget  widget; 

Cardinal  *size; 

XrmValue*  value; 

if  (widget  ==  NULL)  { 

XtErrorMsgC'missingWidget",  "fetchDisplayArg",  "XtToolkitError", 

"FetchDisplayArg  called  without  a  widget  to  reference", 

(String*)NULL,  (Cardinal*) NULL) ; 

value->size  =  sizeof (Display*) ; 

value->addr  =  (caddr_t) &DisplayOfScreen (XtScreenOfOb ject (widget) ); 
} 
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static  XtConvertArgRec  displayConvertArg [ ]  =  { 

{XtProcedureArg,  (XtPointer) FetchDisplayArg,  0}, 
}; 

XtSetTypeConverter (XtQString,   XtQCursor,  CvtStringToCursor, 
displayConvertArg,  XtNumber (displayConvertArg) , 
XtCacheByDisplay,  FreeCursor) ; 

/*ARGSUSED*/ 

static  Boolean  CvtStringToCursor (dpy,  args,  num_args,  fromVal,  toVal, 

closure_ret) 

Display*     dpy; 

XrmValuePtr  args; 

Cardinal    *num_args; 

XrmValuePtr  fromVal; 

XrmValuePtr  toVal; 

XtPointer    *closure  ret; 


if  (*num_args  !=  1) 

XtAppErrorMsg (....); 


Display  *display  =  * (Display**) args [0] .addr, 


Structures 

The  enumerated  type  XtAddressMode  and  the  structure  XtConvertArgRec  specify  how 
each  argument  is  derived.  These  are  defined  in  <X1  II Convert. h>,  as  follows: 

typedef  enum  { 

/*  address  mode  parameter  representation  */ 

XtAddress,        /*  address  */ 

XtBaseOffset,     /*  offset  */ 

Xtlmmediate      /*  constant  */ 

XtResourceString  /*  resource  name  string  */ 

XtResourceQuark   /*  resource  name  quark  */ 
}  XtAddressMode; 

typedef  struct  { 

XtAddressMode  address_mode; 

caddr_t  address_id; 

Cardinal  size; 
}  XtConvertArgRec,  *XtConvertArgList; 
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Name 

XtConverter  —  prototype  procedure  for  an  old-style  resource  converter. 

Synopsis 

typedef  void  (  *XtConverter)  (XrmValue  *,  Cardinal  *,  XrmValue  *,  XrmValue 

*); 

XrmValue  *args; 
Cardinal  *num_args; 
XrmValue  *  from; 
XrmValue  *to; 

Arguments 

args  Specifies  a  list  of  additional  XrmValue  arguments  to  the  converter  if  addi 

tional  context  is  needed  to  perform  the  conversion,  or  specifies  NULL.  For 
example,  a  string-to-font  converter  needs  the  widget's  screen,  or  a 
string-to-pixel  converter  needs  the  widget's  screen  and  colormap. 

num_args  Specifies  the  number  of  additional  XrmValue  arguments,  or  specifies  zero. 

from  Specifies  the  value  to  convert. 

to  Specifies  the  descriptor  to  use  to  return  the  converted  value. 

Description 

The  Intrinsics  provide  a  mechanism  for  registering  converters  that  are  automatically  invoked  by 
the  resource-fetching  routines.  The  Intrinsics  additionally  provide  and  register  several  com 
monly  used  converters.  This  resource  conversion  mechanism  serves  several  purposes: 

•  It  permits  user  and  application  resource  files  to  contain  ASCII  representations  of  non 
textual  values. 

•  It  allows  textual  or  other  representations  of  default  resource  values  that  are  dependent  on 
the  display,  screen,  or  colormap  and  thus  must  be  computed  at  run  time. 

•  It  caches  all  conversion  source  and  result  data.  Conversions  that  require  much  computa 
tion  or  space  (for  example,  string  to  translation  table)  or  that  require  round  trips  to  the 
server  (for  example,  string  to  font  or  color)  are  performed  only  once. 

XtConverter  is  the  old-style  converter  used  until  R4.  The  new-style  converter  is  xtType- 
Converter.  The  two  converter  interfaces  are  not  compatible. 

The  Intrinsics  define  all  the  representations  used  in  the  Core,  Composite,  Constraint,  and  Shell 
widgets.  The  following  resource  converters  are  registered  with  the  Intrinsics: 

From  XtRString  to: 

XtRAcceleratorTable,  XtRBoolean,  XtRBool,  XtRCursor,  XtRDimension, 
XtRDisplay,  XtRFile,  XtRFloat,  XtRFont,  XtRFontStruct,  XtRInt,  Xt- 
RPixel,  XtRPosition,  XtRShort,  XtRTranslationTable,  and  Xt- 
RUnsignedChar. 
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From  XtRColor  to: 

XtRPixel. 
FromXRlnt  to: 

XtRBoolean,  XtRBool,  XtRColor,  XtRDimension,  XtRFloat,  XtRFont,  Xt 
RPixel,  XtRPixmap,  XtRPosition,  XtRShort,  and  XtRUnsignedChar. 

From  XtRPixel  to: 
XtRColor. 

The  string-to-pixel  conversion  has  two  predefined  constants  that  are  guaranteed  to  work  and 
contrast  with  each  other  and  with  xtDe  fault  Background.  They  evaluate  the  black  and 
white  pixel  values  of  the  widget's  screen,  respectively.  For  applications  that  run  with  reverse 
video,  however,  they  evaluate  the  white  and  black  pixel  values  of  the  widget's  screen,  respec 
tively. 

Similarly,  the  string  to  font  and  font  structure  converters  recognize  the  constant  xtDef  ault- 
Font  and  evaluate  this  to  the  font  in  the  screen's  default  graphics  context. 

Type  converters  use  pointers  to  XrmValue  structures  (defined  in  <XlllXresource.h>)  for  input 
and  output  values. 

typedef   struct    { 

unsigned    int    size; 

caddr_t   addr; 
}    XrmValue,     *XrmValuePtr; 

A  resource  converter  procedure  pointer  is  of  type  XtConverter. 
Type  converters  should  perform  the  following  actions: 

Check  to  see  that  the  number  of  arguments  passed  is  correct. 
•         Attempt  the  type  conversion. 

If  successful,  return  a  pointer  to  the  data  in  the  to  parameter;  otherwise,  call  xt- 
WarningMsg  and  return  without  modifying  to. 

Most  type  converters  just  take  the  data  described  by  the  specified  from  argument  and  return 
data  by  writing  into  the  specified  to  argument.  A  few  need  other  information,  which  is  avail 
able  in  the  specified  argument  list. 

A  type  converter  can  invoke  another  type  converter,  which  allows  differing  sources  that  may 
convert  into  a  common  intermediate  result  to  make  maximum  use  of  the  type  converter  cache. 

Note  that  the  address  written  in  to->addr  cannot  be  that  of  a  local  variable  of  the  converter 
because  this  is  not  valid  after  the  converter  returns.  It  should  be  a  pointer  to  a  static  variable,  as 
in  the  example  below  in  which  screenColor  is  returned. 

All  type  converters  should  define  some  set  of  conversion  values  that  they  are  guaranteed  to  suc 
ceed  on  so  these  can  be  used  in  the  resource  defaults.  This  might  be  problematic  with  particu 
lar  conversions,  such  as  fonts  and  colors,  where  there  is  no  string  representation  that  all  server 
implementations  will  necessarily  recognize.  For  resources  like  these,  the  converter  should 
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define    a    symbolic    constant    (for    example,    xtDefaultForeground,    XtDefault- 
Background,  orXtDef  aultFont) . 

Examples 

The  following  example  shows  an  old-style  converter  that  takes  a  string  and  converts  it  to  a 
pixel  value: 

static  void  CvtStringToPixel (args,  num_args,  fromVal,  toVal) 

XrmValuePtr  args; 

Cardinal  *num_args; 

XrmValuePtr  fromVal; 

XrmValuePtr  toVal; 
{ 

static  XColor  screenColor; 

XColor  exactColor; 

Screen  *screen; 

Colormap  colormap; 

Status  status; 

char  message [ 1000] ; 

XrmQuark  q; 

String  params[l]; 

Cardinal  num_params  =  1; 

if  (*num_args  !=  2) 

XtErrorMsgC'cvtStringToPixel",  "wrongParameters", 

"XtToolkitError", 
"String  to  pixel  conversion  needs  screen  and 

colormap  arguments", 
(String  *)NULL,  (Cardinal  *)NULL); 

screen  =  *(  (Screen  **)  args [0] .addr) ; 
colormap  =  *( (Colormap  *)  args [1] .addr) ; 

LowerCase ( (char  *)  f romVal->addr,  message); 
q  =  XrmStringToQuark (message) ; 

if  (q  ==  XtQExtdefaultbackground)  {  done (&screen->white_pixel,  Pixel); 

return;  } 
if  (q  ==  XtQExtdefaultforeground)  {  done (&screen->black_pixel,  Pixel); 

return;  } 

if  ((char)  f romVal->addr [0]  =='#'){   /*  some  color  rgb  definition  */ 

status  =  XParseColor (DisplayOf Screen (screen) ,  colormap, 

(String)  f romVal->addr,  SscreenColor) ; 
if  (status  !=  0)  status  =  XAllocColor (DisplayOf Screen 

(screen),  colormap,  sscreenColor) ; 

}  else   /*  some  color  name  */ 

status  =  XAllocNamedColor (DisplayOf Screen (screen) ,  colormap, 
(String)  f romVal->addr,  SscreenColor,  sexactColor) ; 
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if    (status   ==   0)     { 

params  [0]  =  (String)  f  romVal->addr; 
XtWarningMsgC'cvtStringToPixel",  "noColormap", 

"XtToolkitError", 
"Cannot  allocate  colormap  entry  for  \"%s\"",  params,  &num_params)  ; 

}  else  { 

done  (&  (screenColor  .pixel)  ,    Pixel) 


See  Also 

XtAppAddConverter(l\  XtAppSeffypeConverter(\),  XtConvert(\),  XtDirectConvert(\)t  XtSefType- 
Converter(l),  XtStringConversionWarning(l),  X(TypeConverter(\). 
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Name 

XtConvertSelectionlncrProc  —  prototype  procedure  to  convert  incremental  selection  data. 

Synopsis 

typedef  Boolean  ( *XtConvertSelectionIncrProc) (Widget ,  Atom*,  Atom*,  Atom*, 
XtPointer*,  unsigned  long*,  int*,  unsigned  long*,  XtPointer,  Xt- 
Requestld*) 

Widget  w; 

Atom  *selection; 

Atom  *  target; 

Atom  *type_return; 

XtPointer  * value_return; 

unsigned  long  * length_return; 

int  * forma t_re turn; 

unsigned  long  *max_length; 

XtPointer  client_data; 

XtRequestld  * request_id; 


Arguments 

w 
selection 


Specifies  the  widget  which  currently  owns  this  selection. 

Specifies  the  atom  that  names  the  selection  requested  (for  example,  XA_PRI- 
MARY  or  XA_SECONDARY). 

target  Specifies  the  type  of  information  required  about  selection  (for  example, 

FILENAME,  TEXT,  XA_WINDOW). 

type_return  Specifies  a  pointer  to  an  atom  into  which  the  property  type  of  the  converted 
value  of  the  selection  is  to  be  stored.  For  instance,  both  file  name  and  text 
might  have  property  type  XA_STRING. 

val  ue_return  Specifies  a  pointer  into  which  a  pointer  to  the  converted  value  of  the  selection 
is  to  be  stored.  The  selection  owner  is  responsible  for  allocating  this  storage. 

length_return  Specifies  a  pointer  into  which  the  number  of  elements  in  value  (each  of  size 
indicated  by  format)  is  to  be  stored. 

format_return  Specifies  a  pointer  into  which  the  size  in  bits  of  the  data  elements  of  the 
selection  value  is  to  be  stored. 

max_length  Specifies  the  maximum  number  of  bytes  which  may  be  transferred  at  any  one 
time. 

client_data  Specifies  the  value  passed  in  by  the  widget  when  it  took  ownership  of  the 
selection. 

request_id  Specifies  a  pointer  into  which  the  size  in  bits  of  the  data  elements  of  the 
selection  value  is  to  be  stored. 

Description 

XtConvertSelectionlncrProc  is  registered  with  XtOwnSelectionlncremental. 
This  procedure  is  called  repeatedly  by  the  Intrinsics  selection  mechanism  to  get  the  next 
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incremental  chunk  of  data  from  a  selection  owner.  It  must  return  True  if  the  procedure  has 
succeeded  in  converting  the  selection  data  or  False  otherwise.  On  the  first  call  with  a  particu 
lar  request_id,  the  owner  must  begin  a  new  incremental  transfer  for  the  requested  selection 
and  target.  On  subsequent  calls  with  the  same  request_id,  the  owner  may  assume  that  the 
previously  supplied  value  is  no  longer  needed  by  the  Intrinsics;  that  is,  a  fixed  transfer  area  may 
be  allocated  and  returned  in  value  for  each  segment  to  be  transferred.  This  procedure  should 
store  a  non-NULL  value  in  value  and  zero  in  length_return  to  indicate  that  the  entire  selec 
tion  has  been  delivered.  After  returning  this  final  segment,  the  reguest_id  may  be  re-used 
by  the  Intrinsics  to  begin  a  new  transfer. 

See  Also 

XtGetSelectionValueIncremental(l),  XtGetSelectionVaIuesIncremental(l),  XtOwnS 'election- 
Incremental^), 

XtCancelConvertSelectionProc(2\  XtConvertSelectionProc(2),  XtLoseSelectionIncrProc(2),  Xt- 
SelectionDonelncrProc  (2). 
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Name 

XtConvertSelectionProc  —  prototype  procedure  to  convert  selection  data. 

Synopsis 

typedef  Boolean  (*XtConvertSelectionProc) (Widget,  Atom  *,  Atom  *,  Atom  *, 

XtPointer  *,  unsigned  long  *,  int  *); 
Widget  w; 
Atom  ^selection; 
Atom  *  target; 
Atom  *type_return; 
XtPointer  * value_return; 
unsigned  long  * length_return; 
int  *  format  return; 


Arguments 


selection 


target 


type  return 


value  return 


length_return 
format  return 


Specifies  the  widget  that  currently  owns  this  selection. 

Specifies  the  atom  that  describes  the  type  of  selection  requested  (for 
example,  XA_PRIMARY  or  XA_SECONDARY). 

Specifies  the  target  type  of  the  selection  that  has  been  requested,  which 
indicates  the  desired  information  about  the  selection  (for  example, 
FILENAME,  TEXT,  XA.WINDOW). 

Specifies  a  pointer  to  an  atom  into  which  the  property  type  of  the 
converted  value  of  the  selection  is  to  be  stored.  For  instance,  either  file 
name  or  text  might  have  the  property  type  XA_STRING. 

Specifies  a  pointer  into  which  a  pointer  to  the  converted  value  of  the 
selection  is  to  be  stored.  The  selection  owner  is  responsible  for  allocating 
this  storage.  If  the  selection  owner  has  provided  an  xt Select ion- 
DoneProc  for  the  selection,  this  storage  is  owned  by  the  selection 
owner;  otherwise,  it  is  owned  by  the  Intrinsics  selection  mechanism, 
which  frees  it  by  calling  xtFree  when  it  is  done  with  it. 

Specifies  a  pointer  into  which  the  number  of  elements  in  value  (each  of 
size  indicated  by  format)  is  to  be  stored. 

Specifies  a  pointer  into  which  the  size  in  bits  of  the  data  elements  of  the 
selection  value  is  to  be  stored. 


Description 

Arbitrary  widgets  (possibly  not  all  in  the  same  application)  can  communicate  with  each  other 
by  means  of  the  Toolkit  global  selection  mechanism,  which  is  defined  in  the  Inter-Client  Com 
munications  Manual  (see  Volume  Zero,  X  Protocol  Reference  Manual).  The  Intrinsics  provide 
functions  for  providing  and  receiving  selection  data  in  one  logical  piece  (atomic  transfers). 
The  actual  transfer  between  the  selection  owner  and  the  Intrinsics  is  not  required  to  be  atomic; 
the  Intrinsics  will  break  a  too-large  selection  into  smaller  pieces  for  transport  if  necessary. 
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The  Intrinsics  call  the  selection  owner's  Xt  Convert  Selection?  roc  to  obtain  selection 
data  when  another  client  requests  it  The  XtConvertSeleCtionProc  is  registered  when 
the  selection  owner  asserts  its  ownership. 

The  XtConvertSeleCtionProc  should  return  True  if  the  owner  successfully  converted 
the  selection  to  the  target  type  or  False  otherwise.  If  the  procedure  returns  False,  the  val 
ues  of  the  return  arguments  are  undefined. 

Each  XtConvertSeleCtionProc  should  respond  to  target  value  TARGETS  by  returning  a 
value  containing  the  list  of  the  targets  they  are  prepared  to  convert  their  selection  into.  This  is 
used  by  the  selection  owner.  The  list  of  targets  should  be  an  array  of  interned  Atoms,  and 
return_type  should  be  XA_ATOM. 

Most  type  Atoms  are  defined  in  <XlllXatom.h>.  Those  that  are  not  (for  example,  TARGETS) 
must  be  interned  explicitly  as  Atoms  by  calling  the  Xlib  function  xinternAtom. 

Examples 

The  example  below  shows  code  to  handle  standard  selection  targets.  This  code  is  taken  from 
the  BitmapEdit  widget  developed  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual; 
however,  this  portion  of  it  is  adapted  from  the  standard  client  xclipboard,  and  can  be  copied 
almost  directly  into  your  widget. 

static  Boolean 

convert_proc (w,  selection,  target,  type_return,  value_return, 

length_return,  f ormat_return) 
Widget  w; 
Atom  *selection; 
Atom  * target; 
Atom  *type_return; 
XtPointer  *value_return; 
unsigned  long  *length_return; 
int  *format_return; 

{ 

BitmapEditWidget  cw  =  (BitmapEditWidget)  w; 

int  x,  y; 

int  width,  height; 

XSelectionRequestEvent*  req  =  XtGetSelectionRequest (w, 
*selection,  (XtRequestld)  NULL); 

/*  handle  all  required  atoms,  and  the  one  that  we  use  */ 
if  (*target  ==  XA_TARGETS (XtDisplay (cw) ) )  { 

/*  TARGETS  handling  copied  from  xclipboard. c  */ 
Atom*  target?; 
Atom*  std_targets; 
unsigned  long  std_length; 

XmuConvertStandardSelection(cw,  req->time,  selection, 
target,  type_return, 
(XtPointer*) &std_targets, 
&std_length,  format_return) ; 

*value_return  =  XtMalloc (sizeof (Atom) * (std_length  +  1)); 
targetP  =  * (Atom**) value_return; 
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*length_return  =  std_length  +  1; 

*targetP++  =  cw->bitmapEdit  .  target_atom; 

bcopy  (  (char*)  std_targets,  (char*)  target?,  sizeof  (Atom)  *std_length) 

XtFree  (  (char*)  std_targets)  ; 

*type_return  =  XA_ATOM; 

*format_return  =  sizeof  (Atom)  *  8; 

return  (True)  ; 

} 

/*  Xt  already  handles  MULTIPLE,  no  branch  necessary  */ 
else  if  (*target  ==  cw->bitmapEdit  .  target_atom)  { 
char  *data; 

width  =  cw->bitmapEdit  .  select_end_x  - 

cw->bitmapEdit  .  select_start_x; 
height  =  cw->bitmapEdit  .  select_end_y  - 

cw->bitmapEdit  .  select_start_y  ; 

/*  8  chars  is  enough  for  two  3-digit  numbers  and  two 

delimiters  */ 
*length_return  =  ((width  *  height)  +  8)  *  sizeof  (char)  ; 

data  =  XtMalloc  (*length_return)  ; 
sprintf  (data,  "%d@%d~",  width,  height); 

for  (x  =  0;  x  <  width;  x++)  { 

for  (y  =  0;  y  <  height;  y++)  { 

data  [8  +  x  +  (y  *  width)]  =  cw->bitmapEdit  .cell  [ 
(x  +  cw->bitmapEdit  .  select_start_x)  + 
(  (y  +  cw->bitmapEdit  .  select_start_y)  * 
cw->bitmapEdit  .pixmap_width_in_cells)  ]  ; 


*value_return  =  data; 

*type_return  =  cw->bitmapEdit  .  target_atom; 

*format_return  =  8;   /*  number  of  bits  in  char  */ 
return  (True)  ; 
} 
else  { 

if  (XmuConvertStandardSelection  (cw,  CurrentTime,  selection, 
target,  type_return,  value_return, 
length_return,  format_return)  ) 
return  True; 
else  { 

XtWarningC'bitmapEdit  :  requestor  is  requesting\ 

unsupported  selection  target  type.W); 
return  (False)  ; 
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Overall,  this  code  handles  the  TARGETS  atom  in  the  first  branch,  the  expected  selection  target 
in  the  second,  and  any  remaining  standard  atoms  and  any  unknown  atoms  as  two  cases  in  the 
third  branch.  For  ICCCM-compliant  code,  you  can  copy  this  entire  function  into  your  widget 
and  then  write  just  the  second  branch.  Note  that  branches  that  successfully  provide  the 
requested  data  return  True,  and  ones  that  don't  return  False.  The  ICCCM  also  specifies  that 
functions  implementing  selections  must  be  able  to  respond  to  a  MULTIPLE  target  value,  which 
is  used  to  handle  selections  too  large  to  fit  into  a  single  property.  However,  the  necessary  hand 
ling  is  done  by  the  Intrinsics.  Your  procedures  do  not  need  to  worry  about  responding  to  the 
MULTIPLE  target  value;  a  selection  request  with  this  target  type  will  be  transparently 
transformed  into  a  series  of  smaller  transfers. 

In  the  first  branch  you  will  also  need  to  change  the  reference  to  the  instance  part  field  that 
stores  the  target  atom  used  for  selections,  bitmapEdit .  target_atom.  If  your  widget  uses 
a  predefined  atom  or  one  supported  by  the  Xmu  facility,  you  would  reference  that  atom  here 
instead  of  the  instance  part  field.  If  you  called  XlnternAtom  in  initialize  and  stored 
the  result  in  an  instance  part  field,  you  specify  that  here. 

See  Also 

XtFree(\\  XtGetSelectionValue(\),  XtGetSelectionVatueIncremental(l\  XtO\vnSelection(\\ 
XtConvertSelectionlncrProc  (2),  XtSelectionDoneProc  (2). 
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Name 

XtDestructor  —  prototype  procedure  to  destroy  cached  resource  data. 

Synopsis 

typedef  void  (*XtDestructor)  (XtAppContext,  XrmValue  *,  XtPointer, 

XrmValue  *,  Cardinal  *) 
XtAppContext  app; 
XrmValue  *to; 
XtPointer  converter_data; 
XrmValue  *args; 
Cardinal  *num_args; 

Arguments 

app  Specifies  an  application  context  in  which  the  resource  is  being  freed. 

to  Specifies  a  descriptor  for  the  resource  produced  by  the  type  converter. 

convert er_  data 

Specifies  the  converter_data  returned  by  the  type  converter. 

args  Specifies  the  additional  converter  arguments  as  passed  to  the  type  converter 

when  the  conversion  was  performed. 

num_args  Specifies  the  number  of  additional  converter  arguments. 

Description 

The  destructor  procedure  is  responsible  for  freeing  the  resource  specified  by  the  t  o  argument, 
including  any  auxiliary  storage  associated  with  that  resource,  but  not  the  memory  directly 
addressed  by  the  size  and  location  in  the  to  argument  nor  the  memory  specified  by  the  args. 

See  Also 

XtAppSefTypeConverter  ( 1 ),  XtSefTypeConverter  ( 1 ), 
XfTypeConverter  (2). 
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v  -  Xt  -  Error  Handling  — 

Name 

XtErrorHandler  —  prototype  for  low-level  error  and  warning  handlers. 

Synopsis 

typedef  void  (*XtErrorHandler)  (String)  ; 
String  message; 

Arguments 

message  Specifies  the  error  message. 

Description 

The  function  registered  by  XtAppSetErrorHandler  and  xtAppSetWarningHandler 
is  of  type  XtErrorHandler. 

The  error  handler  should  display  the  message  string  in  some  appropriate  fashion.  Some  appli 
cations  may  wish  to  log  errors  to  a  file  as  well. 

Examples 

The  default  handlers  simply  print  a  message  to  standard  error,  and  exit  (for  errors)  or  return  (for 
warnings),  as  shown  below: 

static  void  _XtDef  aultError  (message) 

String  message; 
{ 

extern  void  exit(); 

(void)  fprintf  (stderr,  "X  Toolkit  Error:  %s\n",  message); 
exit  (1)  ; 
} 

static  void  _XtDefaultWarning  (message) 

String  message; 
{ 

(void)  fprintf  (stderr,  "X  Toolkit  Warning:  %s\n",  message); 

return; 


See  Also 

XtAppError(\\  XtAppSetErrorHandler  •(!),  XtAppSetWarningHandler  (1),  XtAppWarning(\). 
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K     u   W1I     XtErrorMsgHandler 

— Xt-  Error  Handling ' 

Name 

XtErrorMsgHandler  —  prototype  for  high-level  error  and  warning  handlers. 

Synopsis 

typedef  void  ( *XtErrorMsgHandler) (String,  String,  String,  String,  String  *, 

Cardinal  *) ; 
String  name; 
String  type; 
String  class; 
String  defaultp; 
String  *params; 
Cardinal  *num_params; 

Arguments 

name  Specifies  the  name  that  is  concatenated  with  the  specified  type  to  form  the 

resource  name  of  the  error  message. 

type  Specifies  the  type  that  is  concatenated  with  the  name  to  form  the  resource 

name  of  the  error  message. 

class  Specifies  the  resource  class  of  the  error  message. 

defa  ul  tp  Specifies  the  default  message  to  use  if  no  error  database  entry  is  found. 

pa  rams  Specifies  a  pointer  to  a  list  of  values  to  be  substituted  in  the  message. 

numjparams  Specifies  the  number  of  values  in  the  parameter  list. 

Description 

Application-supplied  error  handling  functions,  for  both  warnings  and  fatal  errors,  are  of  type 
XtErrorMsgHandler.  These  functions  can  be  set  with  XtAppSetErrorMsgHandler 
and  XtAppSetWarningMsgHandler. 

The  specified  name  can  be  a  general  kind  of  error,  like  invalidParameters  or  invalid- 
Window,  and  the  specified  type  gives  extra  information.  Standard  print  f  notation  is  used  to 
substitute  the  parameters  into  the  message. 

The  default  Toolkit-supplied  error  and  warning  handler  functions  construct  a  string  and  pass  the 
result  to  XtError  and  xtwarning,  respectively.  Low-level  handlers  are  of  type  XtError- 
Handler. 

The  error  handler  should  make  a  call  to  XtGetErrorDatabase  or  XtAppGetError- 
Database  to  retrieve  the  address  of  the  loaded  error  database  (if  a  database  other  than  the 
default  is  being  used),  and  xtGetErrorDatabaseText  or  xtAppGetErrorDatabase- 
Text  to  actually  retrieve  the  message  from  the  database. 

Examples 

The  example  below  shows  the  default  error  message  handler  from  the  MIT  R4  Intrinsics. 

static  void  _XtDefaultErrorMsg 
(name, type, class, defaultp, params, num_params) 
String  name, type, class, defaultp; 
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String*  params; 
Cardinal*  num_params; 
{ 

char  buffer  [1000]  ,  message  [  1000]  ; 

XtGetErrorDatabaseText  (name,  type,  class,  defaultp,  buffer,  1000)  ; 

if  (params  ==  NULL  |  |  numjparams  ==  NULL  |  |  *num_params  ==  0) 

XtError  (buffer)  ; 
else  { 

int  i  =  *num_params; 
String  par  [10]  ; 
if  (i  >  10) 
i  =  10; 

bcopy(  (char*)params,  (char*)par,  i  *  sizeof  (String)  ); 
bzero(  &par[i],  (10-i)  *  sizeof  (String)  ); 
(void)  sprintf  (message,  buffer,  par[0],  par  [  1  ]  ,  par  [2],  par  [3], 

par[4],  par[5],  par[6],  par[7],  par[8],  par[9]); 
XtError  (message)  ; 
if  (i  !=  *num_params) 

XtWarning(  "some  arguments  in  previous  message  were  lost"); 


See  Also 

XtAppSetErrorMsgHandler  (  1  )  ,  XtAppSeiWarningMsgHandler  (  1  ). 
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/  XtEventHandler 

— Xt-  Event  Handling ' 

Name 

XtEventHandler  —  prototype  event  handler  procedure. 

Synopsis 

typedef  void  ( *XtEventHandler) (Widget,  XtPointer,  XEvent  *,  Boolean  *); 
Widget  w; 

XtPointer  client_data; 
XEvent  *  event; 
Boolean  * continue_to_dispatch 

Arguments 

w  Specifies  the  widget  for  which  to  handle  events. 

client_data      Specifies  the  client-specific  information  registered  with  the  event  handler, 
which  is  usually  NULL  if  the  event  handler  is  registered  by  the  widget  itself. 

event  Specifies  the  triggering  event  for  this  handler. 

continue_to_dispatch 

Specifies  whether  to  call  the  remaining  event  handlers  that  are  registered  for 
the  current  event. 

Description 

Event  handlers  are  of  type  XtEventHandler.  A  widget  registers  an  event  handler  by  calling 
XtAddEventHandler,  specifying  as  the  handler  argument  a  pointer  to  a  procedure  of  this 
type. 

After  receiving  an  event  and  before  calling  any  event  handlers,  the  Boolean  pointed  to  by 
continue_to_dispatch  is  initialized  to  True.  When  an  event  handler  is  called,  it  may 
decide  that  further  processing  of  the  event  is  not  desirable  and  may  store  False  in  this 
Boolean,  in  which  case  any  handlers  remaining  to  be  called  for  the  event  will  be  ignored. 

The  circumstances  under  which  the  Intrinsics  may  add  event  handlers  to  a  widget  are  currently 
implementation-dependent.  Clients  must  therefore  be  aware  that  storing  False  into  the  con- 
tinue_to_dispatch  argument  can  lead  to  portability  problems. 

Most  widgets  need  not  use  event  handlers  explicitly.  Instead  they  use  the  Xt  Translation  Man 
ager  to  accept  events  and  invoke  procedures  based  on  the  interpretation  of  multiple  events. 

Examples 

The  example  below  shows  the  code  from  xterm  that  registers  an  event  handler  for  Focus  In 
and  FocusOut  events,  and  a  gutted  version  of  the  event  handler  itself. 

extern  void  HandleFocusChange  ( ) ; 

static  void  VTInitialize  (request,  new) 
XtermWidget  request,  new; 
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XtEventHandler 


(continued) 


Xt  -  Event  Handling 


XtAddEventHandler (topLevel,  /*  widget  */ 


FocusChangeMask,  /: 

FALSE,  /' 

HandleFocusChange,  /' 

(Opaque) NULL) ;  /' 


event  mask  */ 
non-maskable  events 
event  handler  */ 
client  data  */ 


/*ARGSUSED*/ 

void  HandleFocusChange (w,  unused,  event) 

Widget  w; 

register  XFocusChangeEvent  *event; 

caddr_t  unused;  /*  client_data  */ 

{ 

if (event->type  ==  Focusln) 
/*  process  Focusln  */ 


else  { 
/*  process  FocusOut  */ 


See  Also 

XtAddEventHandler •(!),  XtAddRawEventHandler(\\  XtRemoveEventHandler(\),  XtRemoveRawEvent- 
Handler(l). 
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-X«-  F,,.  Management /  XtFilePrediCate 

Name 

XtFilePredicate  —  prototype  procedure  used  in  filename  evaluation. 

Synopsis 

typedef   Boolean    ( *XtFilePredicate) (String) ; 
String   filename; 

Arguments 

filename  Specifies  a  potential  filename. 

Description 

Filename  evaluation  is  handled  in  an  operating  system-dependent  fashion  by  a  file  predicate 
procedure  of  type  XtFilePredicate.  An  XtFilePredicate  is  registered  in  calls  to 
XtFindFile  or  XtResolvePathname.  This  procedure  will  be  called  with  a  string  that  is 
potentially  a  filename.  The  procedure  returns  True  if  this  string  specifies  a  file  that  is  appro 
priate  for  the  intended  use;  otherwise,  the  procedure  returns  False. 

See  Also 

XtFindFile(\\  XtResolvePathname^). 
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XtlnputCallbackProc  V1 

> Xt  -  Event  Handling  — 

Name 

XtlnputCallbackProc  —  prototype  procedure  called  to  handle  file,  pipe,  or  socket  input. 

Synopsis 

typedef  void  ( *XtInputCallbackProc) (XtPointer,  int  *,  Xtlnputld  *); 
XtPointer  client_data; 
int  *source; 
Xtlnputld  *id; 

Arguments 

dient_data      Specifies  the  client  data  that  was  registered  for  this  procedure  in  xtApp- 
Addlnput. 

source  Specifies  the  source  file  descriptor  generating  the  event. 

id  Specifies  the  ID  returned  from  the  corresponding  XtAppAddlnput  call. 

Description 

An  XtlnputCallbackProc  is  registered  by  calling  XtAppAddlnput.  id  is  the  return 
value  from  the  procedure  that  registered  it. 

An  XtlnputCallbackProc  is  called  when  there  is  activity  in  file  source.  A  procedure  of 
this  type  is  called  to  handle  the  type  of  file  activity  (input,  output)  it  was  registered  for.  Note 
that  because  the  code  for  reading  and  writing  files  varies  between  operating  systems,  this  code 
is  inherently  non-portable. 

Examples 

The  example  below  shows  an  XtlnputCallbackProc  named  get_f  ile_input  together 
with  the  application  used  to  register  it 

/*    header    files    */ 


/*  ARGSUSED  */ 

get_file_input (client_data,  fid,  id) 

XtPointer  client_data;   /*  unused  */ 

int  *fid; 

Xtlnputld  *id; 

{ 

char  buf [BUFSIZ]  ; 

int  nbytes; 

int  i; 


if  ((nbytes  =  read(*fid,  buf,  BUFSIZ))  ==  -1) 
perror ("get_f ile_input") ; 

if  (nbytes) 

for  (i  =  0;  i  <  nbytes;  i++) 
putchar (buf [i] ) ; 
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Xt-  Event  Handling 


(continued) 


Xtln  putCal  I  backProc 


main(argc,  argv) 
int  argc; 
char  **argv; 
{ 

XtAppContext  app_context; 

Widget  topLevel,  goodbye; 

FILE  *fid; 

String  filename; 

topLevel  =  XtVaAppInitialize ( 


&app_context , 
"XFilelnput", 
NULL,  0, 
Sargc,  argv, 
NULL, 
NULL) ; 


/*  Application  context  */ 

/*  Application  class  */ 

/*  command  line  option  list  */ 

/*  command  line  args  */ 

/*  for  missing  app-defaults  file  */ 

/*  terminate  varargs  list  */ 


if  (argv[l]  ==  NULL)  { 

fprintf (stderr, 

"xfileinput:  filename  must  be  specified  on  command  line.Xn") 

exit (1) ; 
} 

filename  =  argv[l]; 


/*  open  file,  pipe,  or  socket  */ 

if  ((fid  =  fopen (filename,  "r"))  ==  NULL) 

fprintf (stderr,  "xfileinput:  couldn't  open  input  file.Xn") 

/*  register  function  to  handle  that  input  */ 
XtAppAddlnput (app_context,  fileno(fid),  XtlnputReadMask, 
get_file_input,  NULL); 

XtRealizeWidget (topLevel) ; 
XtAppMainLoop (app  context); 


See  Also 

XtAppAddInput(\) 
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XtKeyProc  \ 

v Xt- Keyboard  Handling  — 

Name 

XtKeyProc  —  prototype  procedure  to  translate  a  key. 

Synopsis 

typedef  void  (*XtKeyProc)  (Display  *,  KeyCode,  Modifiers,  Modifiers  *, 

KeySym  * ) ; 
Display  *  display; 
KeyCode  keycode; 
Modifiers  modifiers; 
Modifiers  *modifiers_return; 
KeySym  * keysym_return; 

Arguments 

display  Specifies  the  display  from  which  to  translate  the  events. 

keycode  Specifies  the  keycode  that  is  to  be  translated. 

modifiers          Specifies  the  mask  that  indicates  what  modifier  keys  (Shift,  Meta,  Control, 
etc.)  are  pressed. 

modi  fi  ers_re  t  urn 

Specifies  the  mask  of  modifier  keys  that  the  function  actually  evaluated  in 
making  the  conversion. 

keysym_return  Specifies  the  resulting  keysym. 

Description 

The  Resource  Manager  provides  support  for  automatically  translating  keycodes  in  incoming 
key  events  into  keysyms.  Keycode-to-keysym  translator  procedure  pointers  are  of  type  xt- 
KeyProc. 

This  procedure  takes  a  keycode  and  modifiers  and  produces  a  keysym.  For  any  given  key  trans 
lator  function,  modi  fiers_ret  urn  will  be  a  constant  that  indicates  the-subset  of  all  modifi 
ers  that  are  examined  by  the  key  translator. 

The  default  translator  is  XtTranslateKey,  an  XtKeyProc  that  uses  Shift  and  Lock  modifi 
ers  with  the  interpretations  defined  by  the  core  protocol.  The  MIT  R4  code  for  Xt 
TranslateKey  and  associated  internal  routines  is  shown  below. 

Examples 

/* 

*  The  pd->defaultCaseConverter  is  _XtConvertCase  or  the  function 

*  registered  with  XtRegisterCaseConverter . 
*/ 

void  XtTranslateKey (dpy,  keycode,  modifiers, 

modif iers_return,  keysym_return) 
register  Display  *dpy; 
KeyCode  keycode; 
Modifiers  modifiers; 
Modifiers  *modif iers_return; 
KeySym  *keysym_return; 
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register  XtPerDisplay  pd  =  _XtGetPerDisplay (dpy) ; 

int  per; 

register  KeySym  *syms; 

KeySym  sym,  Isym,  usym; 

*modifiers_return  =  (ShiftMask | LockMask)  I  pd->mode_switch; 
if  { (keycode  <  pd->min_keycode)  I  I  (keycode  >  pd->max_keycode) )   { 
*keysym_return  =  NoSymbol; 

return; 
} 

per  =  pd->keysyms_per_keycode; 

syms  =  &pd->keysyms [ (keycode  -  pd->min_keycode)  *  per] ; 
while  ((per  >  2)  &&  (syms [per  -  1]  ==  NoSymbol)) 

per — ; 
if  (  (per  >  2)  &&  (modifiers  &  pd->mode_switch) )  { 

syms  +=  2 ; 
per  -=  2; 
} 
if  (! (modifiers  &  ShiftMask)  && 

(!  (modifiers  &  LockMask)  I  I 
(pd->lock_meaning  ==  NoSymbol) ) )  { 
if  ((per  ==  1)  II  (syms[l]  ==  NoSymbol)) 

(*pd->defaultCaseConverter) (dpy,  syms[0],  keysym_return, 

&usym) ; 
else 

*keysym_return  -  syms[0]; 
} 
else  if  (! (modifiers  &  LockMask)  II 

(dpy->lock_meaning  !=  XK_Caps_Lock) )  { 
if  ((per  ==1)  II  ((usym  =  syms [ 1 ] )  ==  NoSymbol)) 

(*pd->defaultCaseConverter) (dpy,  syms[0],  &lsym,  &usym) ; 
*keysym_return  =  usym; 
} 
else  { 

if  ((per  ==  1)  M  ((sym  =  syms[l])  ==  NoSymbol)) 

sym  =  syms [0] ; 

(*pd->defaultCaseConverter)  (dpy,  sym,  Slsym,  susym) ; 
if  (! (modifiers  &  ShiftMask)  &&  (sym  !=  syms[0])  && 
((sym  !=  usym)  ||  (Isym  ==  usym))) 

(*pd->defaultCaseConverter) (dpy,  syms[0],  Slsym,  &usym) 
*keysym_return  =  usym; 
} 

if  (*keysym_return  ==  XK_VoidSymbol) 
*keysym  return  =  NoSymbol; 
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The  XtPerDisplay  structure  referenced  in  the  example  is  an  internal  structure  used  to  keep 
track  of  variables  that  may  differ  on  a  display-by-display  basis. 

Structures 

typedef   unsigned   int   Modifiers; 

Modifiers  will  be  made  up  of  the  bitwise  OR  the  following  masks: 

Shi f  tMa s k  Shift  key  was  depressed. 

LOG kMa s k  Caps  Lock  key  was  depressed. 

Cont  rolMa  s  k  Control  key  was  depressed. 

ModlMask  Key  defined  as  Modi  was  depressed. 


ModSMa  s  k  Key  defined  as  Mod5  was  depressed. 

StandardMask  (ShiftMask    |    LockMask). 

For  a  more  detailed  discussion  of  processing  keyboard  input,  see  Chapter  13,  Miscellaneous 
Toolkit  Programming  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 

See  Also 

XtConvertCase(l),  XtGetKeysymTable(\),  XtKeysymToKeycodeList(l\  XtRegisterCaseConverter(\\  Xt- 
SetKeyTranslator(\\  XtTranslateKey(\\  XfTranslateKeycode(\). 
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—  Xt- Selections- 


XtLoseSelectionlncrProc 


Name 

XtLoseSelectionlncrProc  —  prototype  procedure  to  release  incremental  selection  ownership. 

Synopsis 

typedef  void  (*XtLoseSelectionIncrProc) (Widget,  Atom*,  XtPointer) 
Widget  w; 
Atom  *selection; 
XtPointer  client_data; 

Arguments 

w  Specifies  the  widget  that  has  lost  the  selection  ownership. 

sel ection         Specifies  the  atom  that  names  the  selection. 

client_data      Specifies  the  value  passed  in  by  the  widget  when  it  took  ownership  of  the 
selection. 

Description 

XtLoseSelectionlncrProc  can  optionally  be  registered  with  XtOwnSelection- 
Incremental,  and  is  called  by  the  Intrinsics  to  inform  the  selection  owner  that  it  no  longer 
owns  the  selection. 

See  Also 

XtGetSelectionValueIncrementol(l),  XtGetSelectionValuesIncremental(\),  XtOwnSelection- 

Incremental(l), 

XtCancelConvertSelectionProc  (2),  XtConvertSelectionlncrProc  (2),  XtLoseSelectionProc  (2), 

XtSelectionDonelncrProc  (2). 
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•Xt- Selections— 


Name 

XtLoseSelectionProc  —  prototype  procedure  called  by  Xt  when  another  client  claims  the  selec 
tion. 

Synopsis 

typedef  void  ( *XtLoseSelectionProc) (Widget ,  Atom  *)/ 
Widget  w; 
Atom  *  selection; 

Arguments 

w  Specifies  the  widget  that  has  lost  selection  ownership. 

selection         Specifies  the  atom  that  describes  the  selection  type. 

Description 

This  procedure  is  called  by  the  Intrinsics  when  the  specified  widget  loses  the  selection.  The 
XtLoseSelectionProc  is  registered  when  a  widget  asserts  selection  ownership  with  xt- 

OwnSelection. 

The  Intrinsics  use  this  procedure  to  inform  the  former  selection  owner  after  the  selection 
changes  hands.  Note  that  this  procedure  does  not  ask  the  widget  to  lose  the  selection  owner 
ship. 

Chapter  10,  Inter  client  Communications,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming 
Manual,  presents  a  complete  example  widget  that  both  sends  and  receives  data  using  selections. 

See  Also 

XtDisownSelection(l),XtGetSelectionValue(l\XtGetSelectionValueIncremental(l),XtOwnSelection(\), 
XtLoseSelectionlncrProc  (2). 
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-Xt  -  Geometry  Management /  XtOrd GrPrOC 

Name 

XtOrderProc  —  Composite  function  to  determine  position  for  new  child. 

Synopsis 

typedef  Cardinal  (*XtOrderProc) (Widget ); 
Widget  w; 

Arguments 

w  Specifies  the  widget. 

Description 

Instances  of  composite  widgets  may  need  to  specify  information  about  the  order  in  which  their 
children  are  kept.  For  example,  an  application  may  want  a  set  of  command  buttons  in  some 
logical  order  grouped  by  function,  and  it  may  want  buttons  that  represent  filenames  to  be  kept 
in  alphabetical  order.  The  insert_position  function  in  the  Composite  widget  instance 
structure  does  this.  You  provide  this  function  by  setting  the  XtNinsertPosition  resource 
of  a  Composite  widget  to  a  function. 

Composite  widgets  that  allow  clients  to  order  their  children  (usually  homogeneous  boxes)  can 
call  their  widget  instance's  insert_position  method  from  the  class's  insert_child 
method  to  determine  where  a  new  child  should  go  in  its  children  array.  Thus,  a  client  of  a 
composite  class  can  apply  different  sorting  criteria  to  widget  instances  of  the  class,  passing  in  a 
different  insert_position  method  when  it  creates  each  composite  widget  instance. 

The  return  value  of  the  insert_position  method  indicates  how  many  children  should  go 
before  the  widget.  Returning  zero  indicates  that  the  widget  should  go  before  all  other  children, 
and  returning  num_children  indicates  that  it  should  go  after  all  other  children.  The  default 
insert_jposition  method  returns  num_children  and  can  be  overridden  by  a  specific 
composite  widget's  resource  list  or  by  the  argument  list  provided  when  the  composite  widget  is 
created. 

See  Also 

Composite®), 

delete _child(4),  insert _chUd(4). 
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--  Xt  -  Resource  Management  — 

Name 

XtResourceDefaultProc  —  prototype  procedure  passed  as  a  resource  converter  when  xt- 

RCallProcis  specified  in  a  resource  list  entry. 

Synopsis 

typedef  void  (*XtResourceDefaultProc)  (Widget,  int,  XrmValue  *) 
Widget  w; 
int  offset; 
XrmValue  *  value; 

Arguments 

w  Specifies  the  widget  whose  resource  is  to  be  obtained. 

offset  Specifies  the  offset  of  the  field  in  the  widget  record. 

value  Specifies  the  resource  value  to  fill  in. 

Description 

Every  resource  has  a  representation  type.  There  are  26  types  defined  by  the  Intrinsics,  and 
additional  user  types  can  be  created  by  registering  a  type  converter  for  them  (see  xtSet- 
TypeConverter). 

Two  special  representation  types  (xtRlmmediate  and  xtRCallProc)  are  usable  only  as 
default  resource  types.  XtRlmmediate  indicates  that  the  value  in  the  def  ault_addr  field 
of  the  xtResource  structure  is  the  actual  value  of  the  resource  rather  than  the  address  of  the 
value.  The  value  must  be  in  correct  representation  type  for  the  resource.  XtRCallProc  indi 
cates  that  the  value  in  the  def  ault_addr  field  of  the  XtResource  structure  is  a  pointer  to 
a  procedure.  This  procedure  is  automatically  invoked  with  the  widget,  resource_of  f  set, 
and  a  pointer  to  the  XrmValue  in  which  to  store  the  result  and  is  an  XtResourceDefault 
Proc. 

The  XtResourceDefaultProc  procedure  should  fill  in  the  addr  field  of  its  value  argu 
ment  with  a  pointer  to  the  default  data  in  its  correct  type. 

The  example  below  shows  an  XtResourceDefaultProc  used  to  obtain  a  pointer  to  the 
current  screen  at  runtime. 

/*ARGSUSED*/ 

void  XtCopyScreen  (widget  ,  offset,  value) 

Widget      widget; 

int         offset; 

XrmValue    *  value; 
{ 

value->addr  =  (caddr_t)  (&widget->core.  screen)  ; 


See  Also 

XtGetApplicationResources(l\  XtGetConstraintResourceList(\  ),  XtGetResourceList(\). 
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Name 

XtSelectionCallbackProc  —  prototype  procedure  called  when  requested  selection  data  arrives. 

Synopsis 

typedef  void  (*XtSelectionCallbackProc) (Widget,  XtPointer,  Atom  *,  Atom  *, 

XtPointer,  unsigned  long  *,  int  *); 
Widget  w; 

XtPointer  client_data; 
Atom  *  selection; 
Atom  *type; 
XtPointer  value; 
unsigned  long  * length; 
int  *  format; 

Arguments 

w  Specifies  the  widget  that  requested  the  selection  value. 

client_data      Specifies  a  value  passed  in  by  the  widget  when  it  requested  the  selection. 
selection         Specifies  the  type  of  selection  that  was  requested. 

type  Specifies   the  representation    type  of  the   selection   value   (for  example, 

XA_STRING).  Note  that  it  is  not  the  target  that  was  requested  but  the  type 
that  is  used  to  represent  the  target.  The  special  X  Toolkit  atom 
XT_CONVERT_FAIL  is  used  to  indicate  that  the  selection  conversion  failed 
because  the  selection  owner  did  not  respond  within  the  Intrinsics'  selection 
timeout  interval. 

value  Specifies  a  pointer  to  the  selection  value.   The  requesting  client  owns  this 

storage  and  is  responsible  for  freeing  it  by  calling  xtFree  when  it  is  done 
with  it 

l  ength  Specifies  the  number  of  elements  in  value. 

format  Specifies  the  size  in  bits  of  the  data  elements  of  value. 

Description 

This  procedure  is  registered  by  the  requestor  with  XtGet  Select  ionValue  or  XtGet - 
SelectionValues,  and  is  then  called  by  the  Intrinsics  selection  mechanism  to  deliver  the 
requested  selection  to  the  requestor.  Data  transfer  proceeds  as  follows:  data  is  requested 
from  the  owner  of  the  selection  with  XtGet  Select  ionValue  or  XtGet  Select  ion- 
Values;  when  the  data  finally  arrives,  the  SelectionCallbackProc  is  invoked  with  the 
actual  data. 

If  the  SelectionNotify  event  returns  a  property  of  None,  this  means  the  conversion  has 
been  refused,  either  because  there  is  no  owner  for  the  specified  selection  or  because  the 
owner  cannot  convert  the  selection  to  the  requested  target  for  any  reason.  In  either  case,  the 
XtSelectionCallbackProc  procedure  is  called  with  a  value  of  NULL  and  a  length  of  0. 

This  procedure  does  not  need  to  worry  about  responding  to  the  MULTIPLE  or  the  TIMESTAMP 
target  values.  A  selection  request  with  the  MULTIPLE  target  type  will  be  transparently 
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transformed  into  a  series  of  calls  to  this  procedure,  one  for  each  target  type,  and  a  selection 
request  with  the  TTMESTAMP  target  value  will  be  answered  automatically  by  the  Intrinsics 
using  the  time  specified  in  the  call  to  XtOwnSelection  or  xtOwnSelection- 
Incremental. 

Data  delivery  is  done  by  callback,  since  the  Intrinsics  may  have  to  perform  multiple  server 
requests  to  get  data,  and  other  events  may  require  processing  ahead  of  the  data  transfer.  There 
fore,  actual  data  delivery  must  occur  asynchronously  with  respect  to  xtGetSelection- 
Value  orXtGetSelectionValues. 

Chapter  10,  Interclient  Communications,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming 
Manual,  presents  a  complete  example  widget  that  both  sends  and  receives  data  using  selections. 

See  Also 

XtDisownSelection(\),  XtGetSelectionValue(l),  XtGetSelectionValueIncremental(\),  XtGetS 'election- 
Values^),  XtO\vnSelection(l),  XtOwnSelectionIncremental(l). 
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—Xt- Selections- 
Name 

XtSelectionDonelncrProc  —  prototype  procedure  to  indicate  completion  of  incremental 

transfer. 

Synopsis 

typedef  void  (*XtSelectionDoneIncrProc) (Widget,  Atom  *,  Atom  *, 

XtRequestld  *,  XtPointer) 
Widget  w; 
Atom  *selection; 
Atom  *  target; 
XtRequestld  *request_id; 
XtPointer  client_data; 

Arguments 

w  Specifies  the  widget  that  owns  the  selection. 

selection         Specifies  the  atom  that  names  the  selection  being  transferred. 
target  Specifies  the  target  type  to  which  the  conversion  was  done. 

request_id       Specifies  an  opaque  identification  for  a  specific  request. 

client_data      Specified  the  value  passed  in  by  the  widget  when  it  took  ownership  of  the 
selection. 

Description 

The  XtSelectionDonelncrProc  procedure  can  optionally  be  registered  with  XtOwn- 
Selectionlncremental,  and  is  called  by  the  Intrinsics  after  the  requestor  has  retrieved 
the  final  (0-length)  segment  of  the  incremental  transfer  to  indicate  that  the  entire  transfer  is 
complete.  If  this  procedure  is  not  specified,  the  Intrinsics  will  free  only  the  final  value  returned 
by  the  selection  owner  using  XtFree. 

See  Also 

XtGetSelectionValueIncremental(\\  XtGetSelectionValuesIncremental(\),  XtOwnS election- 
Incremental^), 

XtCancelConvertSelectionProc  (2),  XtConvertSelectionlncrProc  (2),  XtLoseSelectionlncrProc  (2). 
XtSelectionDoneProc  (2). 
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v Xt  -  Selections— 

Name 

XtSelectionDoneProc  —  prototype  procedure  called  after  a  data  transfer  completes. 

Synopsis 

typedef  void  (*XtSelectionDoneProc) (Widget,  Atom  *,  Atom  *); 
Widget  w; 
Atom  *  selection; 
Atom  *  target; 

Arguments 

w  Specifies  the  widget  that  owns  the  converted  selection. 

selection          Specifies  the  atom  that  describes  the  selection  type  that  was  converted. 
target  Specifies  the  target  type  to  which  the  conversion  was  done. 

Description 

The  Intrinsics  call  the  XtSelectionDoneProc  registered  in  the  call  to  xtOwnSelection 
when  the  data  transfer  is  actually  complete. 

If  the  selection  owner  has  registered  an  XtSelectionDoneProc,  the  function  will  be  called 
once  for  each  conversion  that  it  performs  after  the  converted  value  has  been  successfully 
transferred  to  the  requestor. 

If  the  selection  owner  has  registered  an  XtSelectionDoneProc,  the  selection  owner  also 
owns  the  storage  containing  the  converted  selection  value.  XtSelectionDoneProc  can  be 
used  by  the  selection  owner  to  deallocate  memory  allocated  in  xtConvertSelection- 
Proc,  XtGetSelectionValuelncremental,  and  XtOwnSelectionlncremental. 

Chapter  10,  Interclient  Communications,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming 
Manual,  presents  a  complete  example  widget  that  both  sends  and  receives  data  using  selections. 

See  Also 

XtDisownSelection(l),  XtGetSelectionValue(l),  XtGetSelectionValues(\\  XtOwnSelection(l), 
XtConvertSelectionProc  (2). 
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— Xt- Event  Handling 

Name 

XtTimerCallbackProc  —  prototype  callback  procedure  invoked  when  timeouts  expire. 

Synopsis 

typedef  void  (*XtTimerCallbackProc) (XtPointer,  Xtlntervalld  *); 
XtPointer  client_data; 
Xtlntervalld  * id; 

Arguments 

client_data      Specifies  the  client  data  that  was  registered  for  this  procedure  in  xtApp- 
AddTimeOut. 

id  Specifies  the  ID  returned  from  the  corresponding  xtAppAddTimeOut  call. 

Description 

An  XtTimerCallbackProc  is  invoked  in  response  to  an  expired  timing  interval,  as  set  by 

XtAppAddTimeOut. 

For  a  periodic  wakeup,  the  callback  procedure  must  call  xtAddTimeOut  again  from  this  pro 
cedure. 

For  an  example  of  a  timeout  procedure  and  registration,  see  Chapter  8,  More  Input  Techniques, 
in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 

See  Also 

XtAppAddTimeOut(\\  XtRemoveTimeOut(\). 
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Xt-  Resource  Management — 

Name 

XtTypeConverter  —  prototype  procedure  for  a  new-style  resource  converter. 

Synopsis 

typedef  Boolean  ( ^XtTypeConverter) (Display  *,  XrmValue  *,  Cardinal  *, 

XrmValue  *,  XrmValue  *,  XtPointer  *); 
Display  *  display; 
XrmValue  *args; 
Cardinal  *num_args; 
XrmValue  * from; 
XrmValue  *to; 
XtPointer  *  con verter_ data; 

Arguments 

display  Specifies  the  Display  connection  with  which  this  conversion  is  associated. 

args  Specifies  a  list  of  additional  XrmValue  arguments  to  the  converter  if  addi 

tional  context  is  needed  to  perform  the  conversion,  or  specifies  NULL.  For 
example,  a  string-to-font  converter  needs  the  widget's  screen,  or  a 
string-to-pixel  converter  needs  the  widget's  screen  and  colormap. 

num_args  Specifies  the  number  of  additional  XrmValue  arguments,  or  specifies  zero. 

to  Specifies  a  descriptor  for  a  location  into  which  to  store  the  converted  value. 

convert  er_dat  a 

Specifies  a  location  into  which  the  converter  may  store  converter-specific 
data  that  is  associated  with  this  conversion. 

Description 

The  Intrinsics  provide  a  mechanism  for  registering  converters  that  are  automatically  invoked  by 
the  resource-fetching  routines.  The  Intrinsics  additionally  provide  and  register  several  com 
monly  used  converters.  This  resource  conversion  mechanism  serves  several  purposes: 

•  It  permits  user  and  application  resource  files  to  contain  ASCII  representations  of  non 
textual  values. 

•  It  allows  textual  or  other  representations  of  default  resource  values  that  are  dependent  on 
the  display,  screen,  or  colormap  and  thus  must  be  computed  at  run  time. 

•  It  caches  all  conversion  source  and  result  data.  Conversions  that  require  much  computa 
tion  or  space  (for  example,  string  to  translation  table)  or  that  require  round  trips  to  the 
server  (for  example,  string  to  font  or  color)  are  performed  only  once. 

The  display  argument  is  normally  used  only  when  generating  error  messages,  to  identify  the 
application  context  (with  the  function  xtDisplayToApplicationContext). 

The  to  argument  specifies  the  size  and  location  into  which  the  converter  should  store  the 
converted  value.  If  the  location  is  NULL,  the  converter  should  allocate  appropriate  storage  and 
store  the  size  and  location  into  the  to  descriptor.  If  the  type  converter  allocates  the  storage,  it 
remains  under  the  ownership  of  the  converter  and  must  not  be  modified  by  the  caller.  The  type 
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converter  is  permitted  to  use  static  storage  for  this  purpose  and  therefore  the  caller  must  imme 
diately  copy  the  data  upon  return  from  the  converter.  If  the  location  is  not  NULL,  the  converter 
must  check  the  size  field  to  insure  that  sufficient  space  has  been  allocated  before  storing  the 
converted  value. 

•  If  insufficient  space  is  specified,  the  converter  should  update  the  size  field  with  the  num 
ber  of  bytes  required  and  should  return  False  without  modifying  the  data  at  the  specified 
location. 

•  If  sufficient  space  was  allocated  by  the  caller,  the  converter  should  update  the  size  field 
with  the  number  of  bytes  actually  occupied  by  the  converted  value. 

For  converted  values  of  type  XtRString,  the  size  should  include  the  NULL-terminating  byte, 
if  any.  The  converter  may  store  any  value  it  wishes  in  the  location  specified  in  conver- 
ter_data;  this  data  will  be  passed  to  the  destructor,  if  any,  when  the  resource  is  freed  by  the 
Intrinsics. 

The  converter  must  return  True  if  the  conversion  was  successful  and  must  return  False 
otherwise.  If  the  conversion  cannot  be  performed  due  to  an  improper  source  value,  a  warning 
message  should  be  issued  with  xtAppWarningMsg. 

The  Intrinsics  define  all  the  representations  used  in  the  Core,  Composite,  Constraint,  and  Shell 
widgets.  The  following  resource  converters  are  registered  with  the  Intrinsics: 

From  XtRString  to: 


XtRAcceleratorTable 
XtRAtom 
XtRBoolean 
XtRBool 
XtRCursor 
XtRDimension 
XtRDisplay 
XtRFile 
XtRFloat 
XtRFont 
From  XtRColor  to  XtRPixel. 

From  XRlnt  to: 

XtRBoolean 

XtRBool 

XtRColor 

XtRDimension 

XtRFloat 

XtRFont 

From  XtRPixel  to  XtRColor. 


XtRFontStruct 

XtRInt 

XtRInitialState 

XtRPixel 

XtRPosition 

XtRShort 

XtRTranslationTable 

XtRUnsignedChar 

XtRVisual 


XtRPixel 

XtRPixmap 

XtRPosition 

XtRShort 

XtRUnsignedChar 


The  string-to-pixel  conversion  has  two  predefined  constants  that  are  guaranteed  to  work  and 
contrast  with  each  other  and  with  xtDef  aultBackground.  They  evaluate  the  black  and 
white  pixel  values  of  the  widget's  screen,  respectively.  For  applications  that  run  with  reverse 
video,  however,  they  evaluate  the  white  and  black  pixel  values  of  the  widget's  screen, 
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respectively.  Similarly,  the  string-to-font  and  font-structure  converters  recognize  the  constant 
XtDef  aultFont  and  evaluate  this  in  the  following  manner: 

•  Query  the  resource  database  for  the  resource  whose  full  name  is  xtDef aultFont, 
class  XtDefaultFont  (that  is,  no  widget  name/class  prefixes)  and  use  a  type  xt- 
RString  value  returned  as  the  font  name,  or  a  type  xtRFont  or  xtRFont Struct 
value  directly  as  the  resource  value. 

•  If  the  resource  database  does  not  contain  a  value  for  xtDef  aultFont,  class  xt 
Def  aultFont,  or  if  the  returned  font  name  cannot  be  successfully  opened,  an  imple 
mentation-defined  font  in  ISO8859-1  character  set  encoding  is  opened.   One  possible 
algorithm  is  to  perform  an  XList Fonts  using  a  wildcard  font  name  and  use  the  first 
font  in  the  list.  This  wildcard  font  name  should  be  as  broad  as  possible  to  maximize  the 
probability  of  locating  a  useable  font;  for  example: 

_*_*_*_R_*_*_*_12o-* -*-*-*-! S088 5 9-1 

•  If  no  suitable  ISO8859-1  font  can  be  found,  issue  an  error  message. 

The  String-to-InitialState  conversion  accepts  the  values  NormalState  or  iconicState  as 
defined  by  the  ICCCM. 

The  String-to-Visual  conversion  calls  XMatchVisuallnfo  using  the  screen  and  depth 
resources  from  core_jDart  and  returns  the  first  matching  Visual  on  the  list.  The  widget 
resource  list  must  specify  any  resource  of  type  xtRVisual  after  the  depth  resource.  The 
allowed  string  values  are  the  X  Protocol  visual  class  names:  StaticGray,  StaticColor, 
TrueColor, Grayscale, Pseudocolor,  and  DirectColor. 

Type  converters  use  pointers  to  XrmValue  structures  (defined  in  <Xll/Xresource.h>)  for  input 
and  output  values. 

typedef  struct  { 

unsigned  int  size;  >-' 

caddr_t  addr; 
}  XrmValue,  *XrmValuePtr; 

The  addr  field  specifies  the  address  of  the  data  and  the  size  field  gives  the  total  number  of 
significant  bytes  in  the  data.  For  values  of  type  String,  addr  is  the  address  of  the  first  char 
acter  and  size  includes  the  NULL-terminating  byte. 

Type  converters  should  perform  the  following  actions: 

•  Check  to  see  that  the  number  of  arguments  passed  is  correct. 

•  Attempt  the  type  conversion. 

•  If  successful,  return  a  pointer  to  the  data  in  the  to  parameter;  otherwise,  call  xt- 
WarningMsg  and  return  without  modifying  to. 

Most  type  converters  just  take  the  data  described  by  the  specified  from  argument  and  return 
data  by  writing  into  the  location  specified  in  the  to  argument.  A  few  need  other  information, 
which  is  available  in  the  specified  argument  list. 


416  X  Toolkit  Intrinsics  Reference  Manual 


Xt  -  Resource  Management 


(continued) 


XtTypeConverter 


A  type  converter  can  invoke  another  type  converter,  which  allows  differing  sources  that  may 
convert  into  a  common  intermediate  result  to  make  maximum  use  of  the  type  converter  cache. 

Note  that  if  an  address  is  written  into  to->addr,  it  cannot  be  that  of  a  local  variable  of  the 
converter  because  the  data  will  not  be  valid  after  the  converter  returns.  Static  variables  may  be 
used,  as  in  the  following  example. 

All  type  converters  should  define  some  set  of  conversion  values  that  they  are  guaranteed  to  suc 
ceed  on  so  these  can  be  used  in  the  resource  defaults.  This  might  be  problematic  with  particu 
lar  conversions,  such  as  fonts  and  colors,  where  there  is  no  string  representation  that  all  server 
implementations  will  necessarily  recognize.  For  resources  like  these,  the  converter  should 
define  a  symbolic  constant  (for  example,  xtDefaultForeground,  xtDefault- 
Background,  or  XtDef  aultFont ) . 

Examples 

The  following  example  shows  a  converter  that  takes  a  string  and  converts  it  to  a  pixel  value. 
Note  that  the  display  parameter  is  only  used  to  generate  error  messages;  the  Screen  conversion 
argument  is  still  required  to  inform  the  Intrinsics  that  the  converted  value  is  a  function  of  the 
particular  display  (and  colormap). 


tdefine  done (type,  value)  \ 
{ 

if  (toVal->addr  !=  NULL)  { 

if  (toVal->size  <  sizeof (type) )  { 
toVal->size  =  sizeof (type) ; 
return  False;    \ 
} 

* (type*) (toVal->addr)  =  (value); 
; 
else  { 

static  type  static_val; 
static_val  =  (value); 

toVal->addr  =  (XtPointer) &static_val, 
} 

toVal->size  =  sizeof (type) ; 
return  True; 


static  Boolean  CvtStringToPixel (display,  args,  num_args,  fromVal, 
toVal,  converter  data) 


Display 

*dpy; 

XrmValue 

*args; 

Cardinal 

*num  args; 

XrmValue 

*f  romVal; 

XrmValue 

*toVal; 

XtPointer 

*converter  data; 

static  XColor 

screenColor; 

XColor 

exactColor; 

Screen 

*screen; 

Colormap 

colormap; 

Status 

status; 

char 

message  [1000]  ; 

XrmQuark 

q; 

X  Toolkit  Intrinsics  Reference  Manual 


417 


XtTypeCon verier  (continued)  Xt  -  Resource  Management 

String          params [1]; 
Cardinal         num_params  =  1; 

if  (*num_args  !=  2) 

XtAppErrorMsg (XtDisplayToApplicationContext (dpy) , 

"cvtStringToPixel",  "wrongParameters",  "XtToolkitError", 

"String  to  pixel  conversion  needs  screen  and  colormap  arguments", 

(String  *)NULL,  (Cardinal  *)NULL); 

screen  =  *( (Screen  **)  args [0] . addr) ;  /*  could  also  use  dpy  now  */ 
colormap  =  *( (Colormap  *)  args [1] . addr) ; 

LowerCase ( (char  *)  f romVal->addr,  message); 

if  (  strcmp (message,  "xtdefaultbackground")  ==  0)  { 

done (&screen->white_  pixel,  Pixel); 

} 
if  (  strcmp (message,  "xtdef aultforeground")  ==  0)  { 

done  (&screen->black_  pixel,  Pixel); 

} 

if  ((char)  f romVal->addr [0]  =='#')  {   /*  some  color  rgb  definition  */ 
status  =  XParseColor (DisplayOfScreen (screen) ,  colormap,  (String) 

f romVal->addr,  sscreenColor) ; 
if  (status  !=  0)  { 

status  =  XAllocColor (DisplayOfScreen (screen) ,  colormap,  SscreenColor) 
} 
else   /*  some  color  name  */ 

status  =  XAllocNamedColor (DisplayOfScreen (screen) ,  colormap, 
(String)  f romVal->addr,  fiscreenColor,  SexactColor) ; 
if  (status  ==  0)  { 

params [0] = (String) fromVal->addr; 

XtAppWarningMsg (XtDisplayToApplicationContext (dpy) , 
"cvtStringToPixel",   noColormap",  "XtToolkitError", 
"Cannot  allocate  colormap  entry  for  \"%s\"",  params,  &num_params) 
}  else  { 

done (  SscreenColor .pixel,  Pixel  ); 
} 

/*  converter  data  not  used  here  */ 


See  Also 

XtAppSefTypeConverter(\\  XtCaIlConverter(l),  XtConvertAndStore(\)t  XtDisplayStringConversion- 
Warning(l),  XtSefTypeConverter(l). 
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Name 

XtWorkProc  —  prototype  procedure  for  performing  background  processing. 

Synopsis 

typedef  Boolean  (*XtWorkProc) (XtPointer) ; 
XtPointer  client_data; 

Arguments 

ciient_data      Represents  the  client  data  specified  when  the  work  procedure  was  registered. 

Description 

A  work  procedure  is  an  application-supplied  function  that  is  executed  while  an  application  is 
idle  waiting  for  an  event.  Work  procedures  are  registered  with  xtAppAddWorkProc.  They 
can  perform  any  calculation  that  is  short  enough  that  the  routine  will  return  in  a  small  fraction 
of  a  second.  If  the  work  procedure  is  too  long,  the  user's  response  time  will  suffer. 

If  a  work  procedure  returns  True,  then  Xt  will  remove  it  and  it  will  not  be  called  again.  But  if 
one  returns  False,  it  will  be  called  repeatedly  every  time  there  is  idle  time,  until  the  applica 
tion  calls  XtRemoveWorkProc.  A  work  procedure  would  return  True  if  it  performs  a  one 
time  setup  such  as  creating  a  pop-up  widget.  It  would  return  False  if  it  were  continuously 
updating  a  disk  file  as  security  against  a  system  crash  or  server  connection  failure. 

You  can  register  multiple  work  procedures,  and  they  will  be  performed  one  at  a  time.  The  most 
recent  work  procedure  added  has  the  highest  priority.  Therefore,  for  example,  if  you  want  to 
create  ten  pop-up  widgets  during  idle  time,  you  should  add  ten  work  procedures.  The  pop  up 
that  you  expect  to  need  first  should  be  added  in  the  last  work  procedure  registered. 

Examples 

The  example  below  shows  a  work  procedure  to  create  a  pop-up  widget. 

/*  work  procedure  */ 

Boolean 

create_popup (client_data) 

XtPointer  client_data; 

{ 

Widget  parent  =  (Widget)  client_data; 

Widget  dialog,  dialogDone; 

pshell  =  XtCreatePopupShell (  "pshell",  transientShellWidgetClass, 
parent,  NULL,  0) ; 

dialog  =  XtCreateManagedWidget (  "dialog",  dialogWidgetClass, 
pshell,  NULL,  0) ; 

dialogDone  =  XtCreateManagedWidget (  "dialogDone",  commandWidgetClass, 
dialog,  NULL,  0) ; 

XtAddCallback (dialogDone,  XtNcallback,  DialogDone,  dialog); 
return (True) ;    /*  makes  Xt  remove  this  work  proc  automatically  */ 
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Remember  that  Xt  cannot  interrupt  a  work  procedure  while  it  is  running;  the  procedure  must 
voluntarily  give  up  control  by  returning,  and  it  must  do  so  quickly  to  avoid  slowing  user 
response. 

See  Also 

XtAppAddWorkProc(l),  XlRemoveWorkProc(\). 
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Intrinsics  Classes 


This  section  contains  alphabetically-organized  reference  pages  for  the  Intrin 
sics  widget  classes:  Core,  Composite,  Constraint,  and  Shell  and  its  various 
subclasses.  Each  reference  page  describes  the  class  and  instance  records 
for  those  widget  classes,  as  well  as  the  available  resources  and  their 
defaults. 


In  This  Section: 


Introduction 

ApplicationShell 

Composite 

Constraint 

Core 

Object 

OverrideShell 

RectObj 

Shell 

TopLevelShell 

TransientShell 

VendorShell 

WMShell 


x  Introduction 

—Intrinsics  Classes x 

The  fundamental  abstraction  and  data  type  of  the  X  Toolkit  is  the  widget,  which  is  a  combina 
tion  of  anX  window  and  its  associated  input  and  display  semantics.  A  widget  is  dynamically 
allocated  and  contains  state  information.  Some  widgets  display  information  (for  example,  text 
or  graphics),  while  others  are  merely  containers  for  other  widgets  (for  example,  a  menu  box). 
Some  widgets  are  output-only  and  do  not  react  to  pointer  or  keyboard  input,  and  others  change 
their  display  in  response  to  input  and  can  invoke  functions  that  an  application  has  attached  to 
them. 

Widget  Classes 

Every  widget  belongs  to  exactly  one  widget  class  that  is  statically  allocated  and  initialized  and 
that  contains  the  operations  allowable  on  widgets  of  that  class.  Logically,  a  widget  class  is  the 
procedures  and  data  that  are  associated  with  all  widgets  belonging  to  that  class.  These  proce 
dures  and  data  can  be  inherited  by  subclasses. 

Physically,  a  widget  class  is  a  pointer  to  a  structure.  The  contents  of  this  structure  are  constant 
for  all  widgets  of  the  widget  class  but  will  vary  from  class  to  class.  (Here,  constant  means  the 
class  structure  is  initialized  at  compile-time  and  never  changed,  except  for  a  one-time  class  ini 
tialization  and  in-place  compilation  of  resource  lists,  which  takes  place  when  the  first  widget  of 
the  class  or  subclass  is  created.) 

The  Xt  Intrinsics  define  four  basic  widget  classes,  which  are  used  as  the  foundation  of  all  other 
widgets: 

•  The  Core  widget  class,  which  defines  data  and  procedures  common  to  all  widget  classes. 

•  The  Composite  widget  class,  a  subclass  of  Core.  The  Composite  widget  class  defines 
data  and  procedures  that  are  common  to  those  widgets  designed  to  contain  child  widgets 
and  to  manage  their  geometry. 

•  The  Constraint  widget  class,  a  subclass  of  Composite  that  defines  additional  data  and 
procedures  needed  to  perform  more  complex  geometry  management.   The  Constraint 
widget  class  defines  these  additional  data  and  procedures  by  maintaining  data  structures 
on  a  per-child  basis. 

•  The  Shell  widget  class,  a  subclass  of  Composite  that  defines  additional  data  and  proce 
dures  needed  to  manage  the  interaction  between  applications  and  the  window  manager. 
There  are  actually  several  subclasses  of  shell,  which  are  described  in  detail  on  separate 
manual  pages  later  in  this  section. 

In  addition,  although  widget  writers  are  free  to  treat  Core  as  the  base  class  of  the  widget  hierar 
chy,  there  are  actually  three  classes  above  it  These  classes  are  Object,  RectObj  (Rectangle 
Object)  and  an  unnamed  class  reserved  for  future  use  by  the  X  Consortium.  These  classes  are 
referred  to  generically  as  "objects." 

The  Object  class  contains  the  definitions  of  fields  common  to  all  objects.  It  encapsulates  the 
mechanisms  for  resource  management.  All  objects  and  widgets  are  subclasses  of  Object,  which 
is  defined  by  the  Ob  jectClassPart  and  Ob  jectPart  structures. 

Rectangle  objects  are  a  subclass  of  Object  that  represent  rectangular  areas.  They  encapsulate 
the  mechanisms  for  geometry  management  and  are  called  RectObjs  to  avoid  conflict  with  the 
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Xlib  Rectangle  data  type.  The  "gadgets"  introduced  by  DECWindows  and  OSF's  Motif 
toolkit  (and  adopted  in  R4  by  the  MIT  Athena  widgets)  are  subclasses  of  RectObj. 

The  unnamed  class  between  RectObj  and  Core  is  reserved  for  possible  future  use  by  the  X  Con 
sortium.  The  only  assumptions  that  may  be  made  about  the  unnamed  class  are: 

•  The  core_class .  superclass  field  of  the  class  record  of  Corewidget  contains  a 
pointer  to  the  unnamed  class  record. 

•  When  a  pointer  to  the  unnamed  class  record  is  de-referenced  as  an  ObjectClass,  it 
will  contain  a  pointer  to  the  class  record  of  RectObj  in  its  ob  ject_class .  super 
class  field. 

Except  for  the  above,  the  content  of  the  class  record  for  this  class  and  the  result  of  an  attempt  to 
subclass  or  to  create  a  widget  of  this  unnamed  class  are  undefined. 

By  convention,  the  term  "widget"  refers  only  to  objects  that  are  a  subclass  of  Core  and  the  term 
"non-widget"  refers  to  objects  that  are  not  a  subclass  of  Core. 

To  avoid  conflict  with  previous  widget  code,  the  data  structures  used  by  non-widget  objects  do 
not  follow  all  the  same  conventions  as  those  for  widgets.  In  particular,  the  class  records  are  not 
composed  of  parts  but  instead  are  complete  data  structures  with  "holes"  in  them  for  the  widget 
fields  that  they  do  not  use.  This  allows  the  static  class  initializers  for  existing  widgets  to  remain 
unchanged. 

Widget  Source  File  Organization 

All  MIT-supplied  widgets  have  three  separate  files  associated  with  them: 

•  A  "private"  header  file  (usually  called  WidgetnameP .H)  containing  declarations  needed 
by  the  widget  and  by  any  subclasses. 

•  A  "public"  header  file  (usually  called  Widgetoame.fi)  containing  declarations  needed  by 
application  programmers. 

•  A  source  code  file  (usually  called  Widgetoame.c)  that  initializes  the  widget  data  struc 
tures  and  provides  the  widget  procedures  that  give  the  widget  its  unique  behavior. 

This  separation  of  functions  into  three  files  is  suggested  for  all  widgets,  but  nothing  in  the 
Toolkit  actually  requires  this  format.  In  particular,  a  private  widget  created  for  a  single  applica 
tion  may  easily  combine  the  "public"  and  "private"  header  files  into  a  single  file,  or  the  widget 
may  merge  the  contents  into  another  application  header  file.  Similarly,  the  widget  implementa 
tion  can  be  merged  into  other  application  code. 

Nonetheless,  the  discussion  that  follows  organizes  the  treatment  of  the  elements  that  make  up 
widgets  in  terms  of  the  files  in  which  they  customarily  reside.  At  first,  this  may  make  some 
aspects  of  the  discussion  difficult  to  follow,  since  it  separates  treatment  of  things  that  are  logi 
cally  connected — for  instance,  data  structures  declared  in  the  private  header  file  are  initialized 
in  the  implementation  (.c)  file.  However,  this  organization  has  the  benefit  of  making  clear  just 
where  to  look  for  the  relevant  code. 
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The  Private  Header  File 

The  private  header  file,  WidgetnameP.h,  contains  the  complete  declaration  of  the  class  and 
instance  structures  for  the  widget  and  any  additional  private  data  that  will  be  required  by  antici 
pated  subclasses  of  the  widget  Information  in  the  private  header  file  is  normally  hidden  from 
the  application  and  is  designed  to  be  accessed  only  through  other  public  procedures;  e.g.,  xt- 
SetValues. 

A  widget  instance  is  composed  of  two  parts: 

•  A  data  structure  that  contains  instance-specific  values  (such  as  widget  resources  and  pri 
vate  state  data). 

•  A  data  structure  that  contains  information  that  is  applicable  to  all  widgets  of  that  class 
(such  as  pointers  to  the  widget's  internal  functions,  or  methods). 

Each  of  these  structures  is  built  up  incrementally  out  of  the  corresponding  structures  in  each  of 
its  superclasses.  Thus  a  given  widget  must  declare  a  total  of  four  new  structures: 

•  The  widgetClassPart  (referred  to  colloquially  as  the  Class  Part),  which  contains 
any  new  fields  that  will  be  used  by  all  members  of  the  new  class.  Most  widgets  will  not 
need  new  class  part  fields  (since  most  of  these  contain  pointers  to  information  used  only 
by  the  Xt  Intrinsics).  Instead,  most  widgets  will  just  declare  a  dummy  field  to  keep  the  C 
compiler  happy. 

•  The  widgetClassRec  (the  Class  Record),  which  includes  the  new  vidgetClass- 
P art,  as  well  as  the  corresponding  structures  in  each  of  the  widget's  superclasses.  The 
contents  of  the  three  base  classes  from  which  most  widgets  are  descended  (Core,  Compo 
site,  and  Constraint)  are  described  in  the  reference  pages  for  each  widget  class  later  in 
this  section. 

•  The  hddgetPart  (the  Instance  Part),  which  contains  any  new  fields  that  will  contain 
widget  instance  data.   For  example,  a  widget  wanting  to  do  drawing  might  declare 
resources  (publicly  accessible  variables)  to  hold  colors;  instance  fields  might  also  hold 
private  state  data. 

•  The  uddgetRecord  (the  Instance  Record),  which  includes  the  new  widgetPart,  as 
well  as  the  corresponding  structures  in  each  of  the  widget's  superclasses. 

For  example,  the  definition  of  the  Composite  widget's  CompositePart  (the  instance  part)  is 
as  follows: 

typedef  struct  _CompositePart  { 

WidgetList   children;  /*  array  of  ALL  widget  children     */ 

Cardinal    num_children;  /*  total  number  of  widget  children  */ 

Cardinal    num_slots;  /*  number  of  slots  in  children  a-rray  */ 

XtOrderProc  insert_position;  /*  compute  position  of  new  child     */ 

}  CompositePart, *CompositePtr; 

This  is  then  combined  with  the  previously  defined  CorePart  in  the  complete  Composite 
instance  record  as  follows: 
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typedef  struct  _CompositeRec  { 

CorePart      core; 

CompositePart  composite; 
}  CompositeRec; 

For  more  information  on  the  Class  and  Instance  records,  see  the  reference  pages  for  the  Core, 
Composite,  Constraint  and  Shell  widget  classes,  which  are  found  later  in  this  section. 

It  may  be  necessary  at  times  to  add  new  fields  to  already  existing  widget  class  structures.  To 
permit  this  to  be  done  without  requiring  recompilation  of  all  subclasses,  the  last  field  in  a  class 
part  record  should  be  an  extension  pointer.  If  no  extension  fields  for  a  class  have  yet  been 
defined,  subclasses  should  initialize  the  value  of  the  extension  pointer  to  NULL. 

If  extension  fields  exist,  as  is  the  case  with  the  Composite,  Constraint  and  Shell  classes,  sub 
classes  can  provide  values  for  these  fields  by  setting  the  extension  pointer  for  the  appropriate 
part  in  their  class  structure  to  point  to  a  statically  declared  extension  record  containing  the 
additional  fields. 

Setting  the  extension  field  is  never  mandatory;  code  that  uses  fields  in  the  extension  record 
must  always  check  the  extension  field  and  take  some  appropriate  default  action  if  it  is  NULL. 

To  permit  multiple  subclasses  and  libraries  to  chain  extension  records  from  a  single  extension 
field,  extension  records  should  be  declared  as  a  linked  list  and  each  extension  record  definition 
should  contain  the  following  four  fields  at  the  beginning  of  the  structure  declaration: 

struct    { 

XtPointer  next_extension; 
XrmQuark  record_type; 
long  version; 
Cardinal  record_size; 


next_extension  Specifies  the  next  record  in  the  list,  or  specifies  NULL.  , 

record_type          Specifies  the  particular  structure  declaration  to  which  each  extension 
record  instance  conforms. 

version  Specifies  a  version  ID  symbolic  constant  supplied  by  the  definer  of  the 

structure. 

record_si  ze         Specifies  the  total  number  of  bytes  allocated  for  the  extension  record. 

The  record_type  field  identifies  the  contents  of  the  extension  record  and  is  used  by  the 
definer  of  the  record  to  locate  its  particular  extension  record  in  the  list.  record_type  is  nor 
mally  assigned  the  result  of  XrmSt  ringToQuark  for  a  registered  string  constant.  The  Intrin 
sics  reserve  for  future  standard  uses  all  record  type  strings  beginning  with  the  two  characters 
"XT".  The  value  NULLQUARK  may  also  be  used  by  the  class  part  owner  in  extension  records 
attached  to  its  own  class  part  extension  field  to  identify  the  extension  record  unique  to  that  par 
ticular  class. 

The  version  field  is  an  owner-defined  constant  that  may  be  used  to  identify  binary  files  that 
have  been  compiled  with  alternate  definitions  of  the  extension  record  data  structure.  The  pri- 
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vate  header  file  for  a  widget  class  should  define  a  symbolic  constant  for  subclasses  to  use  to  ini 
tialize  this  field. 

The  record_size  field  value  includes  the  four  common  header  fields  and  should  normally 
be  initialized  with  sizeof  () .  In  addition,  the  private  header  file  may  define  constants  or 
other  special  data.  For  example,  the  Core,  Composite,  and  Constraint  classes  define  macros 
that  can  be  used  by  subclasses  to  inherit  widget  methods.  (See  the  individual  reference  pages 
for  details.) 

Finally,  if  a  widget  defines  any  special  representation  types  to  be  used  for  resource  conversion, 
the  constants  used  to  represent  them  should  be  defined  in  the  private  header  file.  Standard  rep 
resentation  types  are  defined  in  <Xll/StringDefs.h>. 

The  Public  Header  File 

The  public  header  file  contains  declarations  that  will  be  required  by  any  application  module 
that  needs  to  refer  to  the  widget;  whether  to  create  an  instance  of  the  class,  to  perform  an  xt- 
Setvalues  operation,  or  to  call  a  public  routine  implemented  by  the  widget  class. 

Typically,  the  public  header  file  contains  documentation  of  the  resources  used  by  the  widget 
class  (including  those  inherited  from  superclasses),  and  declarations  of  any  new  resource  names 
that  are  not  in  <Xll/StringDefs.h>. 

The  public  header  file  also  contains  declarations  for  the  widget  class  data  types  and  class  record 
pointer.  For  example,  for  a  label  widget,  these  declarations  might  be  as  follows: 

extern  WidgetClass  labelWidgetClass; 

typedef  struct  _LabelClassRec  *LabelWidgetClass; 
typedef  struct  _LabelRec       *LabelWidget; 

The  public  header  file  may  also  include  declarations  of  functions  specific  to  the  widget  class. 

The  Implementation  File 

The  implementation  (.c)  file  implements  the  widget  class  itself.  The  unique  part  of  this  file  is 
the  declaration  and  initialization  of  the  widget  class  record  structure  and  the  declaration  of  all 
resources  and  action  routines  added  by  the  widget  class. 

The  .c  file  for  a  widget  contains  the  structure  initializer  for  the  class  record,  which  contains  the 
following  parts: 

•  Class    information    (for    example,    superclass,    class_name,    widget_size, 
class_initialize,and  class_inited) 

•  Data  constants  (for  example,   resources  and  num_re sources,  actions  and 
num_actions,  visible_interest,   compress_motion,  compress_expo- 
sure,  and  version) 

•  Widget  operations  (for  example,  the  core  methods  initialize,  realize,  destroy, 
resize,  expose,  set_values,  accept_f  ocus,  and  any  operations  specific  to  the 
widget) 
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The  superclass  field  points  to  the  superclass  widgetClass  record.  For  direct  subclasses  of 
the  generic  core  widget,  superclass  should  be  initialized  to  the  address  of  the  widgetciass- 
Rec  structure.  The  superclass  is  used  for  class  chaining  operations  and  for  inheriting  or  envel 
oping  a  superclass's  operations. 

The  class_name  field  contains  the  text  name  for  this  class  (used  by  the  resource  manager). 
For  example,  the  Label  widget  has  the  string  "Label".  More  than  one  widget  class  can  share 
the  same  text  class  name. 

The  widget_size  field  is  the  size  of  the  corresponding  widget  instance  structure  (not  the 
size  of  the  Class  structure). 

The  version  field  indicates  the  Toolkit  implementation  version  number  and  is  used  for  run 
time  consistency  checking  of  the  X  Toolkit  and  widgets  in  an  application.  Widget  writers  must 
set  it  to  the  implementation-defined  symbolic  value  XtVersion  in  the  widget  class  structure 
initialization.  Those  widget  writers  who  believe  that  their  widget  binaries  are  compatible  with 
other  implementations  of  the  Intrinsics  can  put  the  special  value  xtVersionDontCheck  in 
the  version  field  to  disable  version  checking  for  those  widgets.  If  a  widget  needs  to  compile 
alternative  code  for  different  revisions  of  the  Intrinsics  interface  definition,  it  may  use  the  sym 
bol  XtSpecif icationRelease. 

The  extension  field  is  for  future  upwards  compatibility.  If  you  add  additional  fields  to  class 
parts,  all  subclass  structure  layouts  change,  requiring  complete  recompilation.  To  allow  clients 
to  avoid  recompilation,  an  extension  field  at  the  end  of  each  class  part  can  point  to  a  record 
that  contains  any  additional  class  information  required. 

For  more  information,  see  the  discussion  of  the  class  and  instance  structures  on  each  of  the 
widget  reference  pages  in  this  section. 

Resources 

Each  widget  optionally  declares  and  initializes  a  resource  structure  containing  the  name,  class, 
representation  type,  and  default  value  (which  may  be  overridden  at  various  points)  for  each 
resource. 

On  each  of  the  reference  pages  that  follow,  we  provide  a  table  of  the  resources  defined  by  each 
widget  class.  In  addition  to  the  resource  name,  class,  representation,  and  default  value,  a  fifth 
column  lists  a  code  consisting  of  one  or  more  of  the  letters  C,  S,  and  G.  This  code  indicates 
whether  the  resource  can  be  set  when  the  widget  is  created  (C),  whether  it  can  be  set  with  xt  - 
SetValues  (S),  and  whether  it  can  be  read  with  xtGetValues  (G).  (We've  adopted  this 
useful  convention  from  the  Motif  Programmer' s  Reference  Manual,  which  provides  this  infor 
mation  for  Motif  Widgets.) 


428  X  Toolkit  Intrinsics  Reference  Manual 


—  Intrinsics  Classes- 


ApplicationShell 


Name 

ApplicationShell  widget  class  —  main  shell  for  an  application. 

Synopsis 

#include  <xll/StringDef s.h> 
tinclude  <xll/Intrinsic.h> 

widget  =  XtAppInitialize (  .  .  .  ) 
or 

widget  =  XtAppCreateShell (app_name,  app_class, 

applicationShellWidget Class, 

Class  Hierarchy 

Core  ->  Composite  ->  Shell  ->  WMShell  ->  VendorSheU  ->  TopLevelShell  -»  ApplicationShell 

Description 

The  ApplicationShell  widget  class  is  a  subclass  of  TopLevelShell  that  is  used  for  normal  top 
level  application  windows.  An  instance  of  this  widget  class  is  usually  created  by  a  call  to  xt- 
Applnitialize  (in  R4),  Xtlnitialize,  or  XtCreateApplicationShell. 

Class  and  Instance  Structures 

The  ApplicationShellClassPart  contains  no  additional  class  fields.  Its  declaration  in 
<XlllShellP.h>  is  similar  to  those  of  the  other  shells: 


typedef   struct    { 

XtPointer   extension; 
}    ApplicationShellClassPart; 


/*   pointer   to   extension    record    */ 


The  extension  field  is  NULL. 

The  instance  structure,  ApplicationShellPart,  is  declared  as  follows: 

typedef   struct    { 

char    *class; 

XrmClass  xrm_class; 

int  argc; 

char    **argv; 
}    ApplicationShellPart; 


Resources 

Application  shells  have  the  the  following  resources  in  addition  to  those  inherited  from  super 
classes: 


Name 

Class 

Type 

Default 

Access 

XtNargc 
XtNargv 

XtCargc 
XtCargv 

int 
String* 

0 
NULL 

CG 
CG 
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The  argc  and  argv  resources  are  used  to  initialize  the  standard  property  WM_COMMAND. 
See  Chapter  10,  Interclient  Communications  in  Volume  Four,  X  Toolkit  Intrinsics  Program 
ming  Manual  for  more  details. 
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Composite 


Name 

Composite  widget  class  —  defines  methods  for  geometry  management. 

Synopsis 

#include  <Xll/StringDef s .h> 
#include  <Xll/Intrinsic .h> 

The  predefined  class  record  and  pointer  for  CompositeClassRec  are: 

extern  CompositeClassRec  CompositeClassRec; 
extern  WidgetClass  compositeWidgetClass; 

The  opaque  types  CompositeWidget  and  CompositeWidgetClass  and  the  opaque 
variable  compositeWidgetClass  are  defined  for  generic  operations  on  widgets  that  are  a 
subclass  of  CompositeWidget. 

Class  Hierarchy 

Core  — »  Composite 

Description 

The  Composite  widget  class  is  a  subclass  of  Core  that  defines  methods  for  geometry  manage 
ment  Any  widget  that  is  capable  of  managing  child  widgets  should  be  a  subclass  of  the  Com 
posite  widget. 

The  class  and  instance  structures  are  defined  in  <X1  II Composite?. h>. 
The  composite  class  part  is  defined  as  follows: 


typedef  struct  _CompositeClassPart  { 

XtGeometryHandler  geometry_manager; /*  geometry  manager  for  children  */ 
XtWidgetProc  change_managed;       /*  change  managed  state  of  child  */ 
XtWidgetProc  insert_child;         /*  physically  add  child  to  parent  */ 
XtWidgetProc  delete_child;         / 
XPointer  extension;  / 

}  CompositeClassPart, *CompositePartPtr; 

The  extension  record  defined  for  CompositeClassPart  with  record_type  equal  to 
NULLQUARK  is  CompositeClassExtensionRec. 


physically  add  child  to  parent 
physically  remove  child  */ 
pointer  to  extension  record  */ 


typedef  struct  { 

XtPointer  next_extension;   /' 
XrmQuark  record  type;       /' 


next  record  is  linked  list, 
quark  for  record  type, 
or  NULLQUARK  for  own  type  */ 
XtCompositeClassExtension  */ 
use  sizeofO  */ 


or  NULL  */ 


long  version;  /: 

Cardinal  record_size;  /' 
Boolean  accept s_objects; 

}  CompositeClassExtensionRec,  *CompositeClassExtension; 
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Composite  widget  classes  have  the  composite  fields  immediately  following  the  core  fields: 

typedef  struct  { 

CoreClassPart  core_class; 

CompositeClassPart  compos it e_c lass; 

}  CompositeClassRec,  *CompositeWidgetClass; 

The  composite  instance  part  is  defined  as  follows: 


/*  array  of  ALL  widget  children  */ 

/*  total  number  of  widget  children  */ 

/*  number  of  slots  in  children  array  */ 

/*  compute  position  of  new  child  */ 


typedef  struct  _CompositePart  { 

WidgetList   children; 

Cardinal    num_children; 

Cardinal     num_slots; 

XtOrderProc  insert_position; 
}  CompositePart, *CompositePtr; 

Note  that  this  instance  record  contains  a  method.  (Methods  are  generally  kept  in  the  class 
record,  but  many  different  subclasses  of  Composite  may  need  a  private  XtOrderProc,  so  it  is 
kept  in  the  instance  record.) 

Composite  widgets  have  the  composite  fields  immediately  following  the  core  fields: 

typedef  struct  { 

CorePart  core; 

CompositePart  composite; 

}  CompositeRec,  *CompositeWidget; 

Resources 

The  resource  names,  classes  and  representation  types  specified  in  the  Composite  resource  list 
are: 


Name 

Class 

Representation 

Default 

Access 

XtNchildren 

XtCReadOnly 

XtRWidgetList 

NULL 

G 

XtNinsertPosition 

XtCInsertPosition 

XtRFunction 

Internal  function 

CSG 

InsertAtEnd 

XtNnumChildren 

XtCReadOnly 

XtRCardinal 

0 

G 

The  default  values  for  the  composite  fields,  which  are  filled  in  by  the  Composite  resource  list 
and  the  Composite  initialize  procedure,  are: 


Field 


children 
num_children 
num_slots 
insert_position 


Default  Value 


NULL 

0 

0 

Internal  function   InsertAtEnd 


The  fields  children,  num_children,  and  insert_position  are  declared  as  resources. 
XtNinsertPosition  is  a  sellable  resource;  XtNchildren  and  XtNnumChildren  may 
be  read  by  any  client,  but  they  should  only  be  modified  by  the  composite  widget  itself. 
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Methods 

All  composite  methods  are  described  on  reference  pages  in  Section  4.  Detailed  discussions  and 
example  programs  performing  geometry  management  are  contained  in  Chapter  11,  Geometry 
Management,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 

See  Also 

Core(3\ 

change _managed(4),  delete_child(4),  geometry _manager(4),  insert _child(4),  insert _position(4). 
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Name 

Constraint  widget  class  —  provides  data  structures  for  a  widget's  parent. 

Synopsis 

#include   <Xll/StringDef s . h> 
tinclude    <Xll/Intrinsic ,h> 

The  predefined  class  record  and  pointer  for  ConstraintClassRec  are: 

extern   ConstraintClassRec   ConstraintClassRec; 
extern  WidgetClass   constraintWidgetClass; 

The  opaque  types  ConstraintWidget  and  ConstraintWidgetClass  and  the  opaque 
variable  constraintWidgetClass  are  defined  for  generic  operations  on  widgets  that  are  a 
subclass  of  ConstraintWidgetClass.  The  symbolic  constant  for  the  Constraint- 
ClassExtension  version  ID  is  XtConstraintExtensionVersion. 

Class  Hierarchy 

Core  ->  Composite  — » Constraint 

Description 

Constraint  widgets  are  a  subclass  of  compositeWidgetClass.  Their  name  is  derived  from 
the  fact  that  they  may  manage  the  geometry  of  their  children  based  on  constraints  associated 
with  each  child.  These  constraints  can  be  as  simple  as  the  maximum  width  and  height  the  par 
ent  will  allow  the  child  to  occupy  or  as  complicated  as  how  other  children  should  change  if  this 
child  is  moved  or  resized.  Constraint  widgets  let  a  parent  define  resources  that  are  supplied  for 
their  children.  For  example,  if  the  Constraint  parent  defines  the  maximum  sizes  for  its  children, 
these  new  size  resources  are  retrieved  for  each  child  as  if  they  were  resources  that  were  defined 
by  the  child  widget  Accordingly,  constraint  resources  may  be  included  in  the  argument  list  or 
resource  file  just  like  any  other  resource  for  the  child. 

Constraint  widgets  have  all  the  responsibilities  of  normal  composite  widgets  and,  in  addition, 
must  process  and  act  upon  the  constraint  information  associated  with  each  of  their  children. 

To  make  it  easy  for  widgets  and  the  Intrinsics  to  keep  track  of  the  constraints  associated  with  a 
child,  every  widget  has  a  constraints  field,  which  is  the  address  of  a  parent-specific  structure 
that  contains  constraint  information  about  the  child.  If  a  child's  parent  is  not  a  subclass  of 
constraintWidgetClass,  then  the  child's  constraints  field  is  NULL. 

Note  that  the  constraint  data  structures  are  transparent  to  the  child;  that  is,  when  a  child  is  man 
aged  by  a  parent  that  is  a  subclass  of  a  constraint  widget,  there  is  no  difference,  as  far  as  the 
child  is  concerned,  from  being  managed  by  a  normal  composite  widget. 

The  values  passed  to  the  parent's  constraint  set_values  method  are  the  same  as  those  pas 
sed  to  the  child's  class  set_values  method.  A  class  can  specify  NULL  for  the  set_values 
field  of  the  Const  raintPart  if  it  need  not  compute  anything. 

The  constraint  set_values  method  should  recompute  any  constraint  fields  derived  from  con 
straint  resources  that  are  changed.  Further,  it  should  modify  the  widget  fields  as  appropriate. 
For  example,  if  a  constraint  for  the  maximum  height  of  a  widget  is  changed  to  a  value  smaller 
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than  the  widget's  current  height,  the  constraint  set_values  method  should  reset  the  height 
field  in  the  widget 

The  class  and  instance  structures  are  defined  in  <XlllConstrainP.h>. 
The  class  record  defines  the  actual  data  in  the  form  of  resources: 

typedef  struct  _ConstraintClassPart  { 

XtResourceList  resources;        /*  constraint  resource  list  */ 

Cardinal  num_resources;          /*  number  of  constraints  in  list  */ 

Cardinal  constraint_size;        /*  size  of  constraint  record  */ 

XtlnitProc  constraint_initialize; /*  constraint  initialization  */ 

XtWidgetProc  constraint_destroy;  /*  constraint  destroy  proc  */ 

XtSetValuesFunc  set_values;      /*  constraint  set_values  proc  */ 

XtPointer  extension;  /*  pointer  to  extension  record  */ 

}  ConstraintClassPart; 

The  extension  record  defined  for  ConstraintClassPart  with  record_type  equal  to 
NULLQUARK  is  ConstraintClassExtensionRec. 

typedef   struct    { 

XtPointer   next_extension;  /*    next    record    is    linked   list,    or   NULL    */ 

XrmQuark   record_type;  /*    quark    for   record   type, 

*    or   NULLQUARK    for    own    type    */ 

long   version;  /*    XtConstraintExtensionVersion    */ 

Cardinal    record_size;  /*    use    sizeof()     */ 

XtArgsProc  get_values_hook; 
}    ConstraintClassExtensionRec,    *ConstraintClassExtension; 

Constraint  widget  classes  have  the  constraint  fields  immediately  following  the  composite  fields: 

typedef  struct  { 

CoreClassPart  core_class; 

Compos iteCl a ssPart  compos ite_class; 

ConstraintClassPart  const raint_class; 

}  ConstraintClassRec,  *ConstraintWidgetClass; 

The  instance  record  defines  no  new  fields,  other  than  a  dummy  field  to  satisfy  the  C  compiler. 

typedef  struct  _ConstraintPart  { 

XtPointer  dummy;  /*  No  new  fields,  keep  C  compiler  happy  */ 

}  ConstraintPart; 

Constraint  widgets  have  the  constraint  fields  immediately  following  the  composite  fields: 

typedef  struct  { 

CorePart  core; 

CompositePart  composite; 

ConstraintPart  constraint; 

}  ConstraintRec,  *ConstraintWidget; 

Subclasses  of  a  Constraint  widget  can  add  additional  constraint  fields  to  their  superclass.  To 
allow  this,  widget  writers  should  define  the  constraint  records  in  their  private  .h  file  by  using 
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the  same  conventions  as  used  for  widget  records.  For  example,  a  widget  that  needs  to  maintain 
a  maximum  width  and  height  for  each  child  might  define  its  constraint  record  as  follows: 

typedef  struct  { 

Dimension  max_width, max_height; 
}  MaxConstraintPart; 

typedef  struct  { 

MaxConstraintPart  max; 
}  MaxConstraintRecord, *MaxConstraint; 

A  subclass  of  this  widget  that  also  needs  to  maintain  a  minimum  size  would  define  its  constraint 
record  as  follows: 

typedef  struct  { 

Dimension  min_width,min_height; 
}  MinConstraintPart; 

typedef  struct  { 

MaxConstraintPart  max; 

MinConstraintPart  min; 
}  MaxMinConstraintRecord, *MaxMinConstraint ; 

Constraints  are  allocated,  initialized,  deallocated  and  otherwise  maintained  insofar  as  possible 
by  the  Intrinsics.  The  constraint  class  record  part  has  several  entries  that  facilifc  te  this.  All 
entries  in  Const raintClassPart  are  information  and  procedures  that  are  defined  and 
implemented  by  the  parent,  but  they  are  called  whenever  actions  are  performed  on  the  parent's 
children. 

The  Xt Great eWidget  function  uses  the  const  raint_size  field  to  allocated  a  constraint 
record  when  a  child  is  created.  The  constraint_size  field  gives  the  number  of  bytes 
occupied  by  a  constraint  record.  xtCreateWidget  also  uses  the  constraint  resources  to  fill 
in  resource  fields  in  the  constraint  record  associated  with  a  child.  It  then  calls  the  constraint 
initialize  methods  so  that  the  parent  can  compute  constraint  fields  that  are  derived  from 
constraint  resources  and  can  possibly  move  or  resize  the  child  to  conform  to  the  given  con 
straints. 

The  xtGetValues  and  xtSetValues  functions  use  the  constraint  resources  to  get  the  val 
ues  or  set  the  values  of  constraint  associated  with  a  child.  XtSetValues  then  calls  the  con 
straint  set_values  methods  so  that  a  parent  can  recompute  derived  constraint  fields  and 
move  or  resize  the  child  as  appropriate. 

If  the  Constraint  widget  or  any  of  its  superclasses  have  declared  a  Const raintClass- 
Extension  record  in  the  constraint  class  part  extension  fields  with  a  record  type  of 
NULLQUARK,  and  if  the  get_values_hook  field  in  the  extension  record  is  non-NULL,  then 
XtGetValues  calls  the  get_values_hook  method(s)  to  allow  the  parent  to  return  derived 
constraint  fields. 

The  xtDestroyWidget  function  calls  the  constraint  destroy  method  to  deallocate  any 
dynamic  storage  associated  with  a  constraint  record.  The  constraint  record  itself  must  not  be 
deallocated  by  the  constraint  destroy  method;  XtDestroyWidget  does  this  automatically. 
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Resources 

The  Constraint  CoreClassPart  and  ConstraintClassPart  resource  lists  are  empty; 
no  additional  resources  beyond  those  declared  by  Composite  are  defined  for  Constraint. 

Methods 

All  Constraint  methods  are  described  on  reference  pages  in  Section  4. 

See  Also 

Core(3), 

Constraint  destroy (4),  get_values_hook(4)t  Constraint  initialize (4),  Constraint  set_values(4). 
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Name 

Core  widget  class  —  fundamental  widget 

Synopsis 

#include  <Xll/StringDefs . h> 
#include  <Xll/Intrinsic .h> 

The  predefined  class  record  and  pointer  for  widgetClassRec  are: 

extern   WidgetClassRec   widgetClassRec; 

#define   coreClassRec   widgetClassRec 

extern   WidgetClass   widgetClass,    coreWidgetClass; 

The  opaque  types  widget  and  WidgetClass  and  the  opaque  variable  widgetClass  are 
defined  for  generic  actions  on  widgets. 

Class  Hierarchy 

Object  ->  RectObj  ->  unnamed  ->  Core 

Description 

The  Core  widget  class  is  the  most  fundamental  type  of  widget.  All  other  widgets  are  subclasses 
of  it  Widgets  consist  of  two  data  structures:  a  class  record  (CoreClassPart)  and  an 
instance  record  (CorePart).  Both  records  are  defined  in  <Xll/CoreP.h>.  Volume  Four,  X 
Toolkit  Intrinsics  Programming  Manual,  discusses  how  the  Intrinsics  support  object-oriented 
programming.  The  Core  widget  itself  is  described  there  also,  as  is  a  template  widget. 

The  Release  4  data  structures  are  described  here.  They  differ  only  in  minor  ways  from  the 
Release  3  structures. 

Private  Header  File 

The  class  and  instance  structure  are  defined  in  <XlllCoreP.h>. 

The  ClassPart  is  defined  below: 

typedef  struct  _CoreClassPart  { 

WidgetClass  superclass;  /*  pointer  to  superclass  ClassRec  */ 

String  class_name;  /*  widget  resource  class  name  */ 

Cardinal  widget_size;  /*  size  in  bytes  of  widget  record  */ 

XtProc  class_initialize;  /*  class  initialization  proc  */ 
XtWidgetClassProc  class_part_initialize; /*  dynamic  initialization  */ 

XtEnum  class_inited;  /*  has  class  been  initialized?  */ 

XtlnitProc  initialize;  /*  initialize  subclass  fields  */ 

XtArgsProc  initialize_hook;  /*  notify  that  initialize  called  */ 

XtRealizeProc  realize;  /*  XCreateWindow  for  widget  */ 

XtActionList  actions;  /*  widget  semantics  name  to  proc  map  */ 

Cardinal  num_actions;  /*  number  of  entries  in  actions  */ 

XtResourceList  resources;  /*  resources  for  subclass  fields  */ 

Cardinal  num_resources;  /*  number  of  entries  in  resources  */ 

XrmClass  xrm_class;  /*  resource  class  quarkified  */ 

Boolean  compress_motion;  /*  compress  MotionNotify  for  widget  */ 

XtEnum  compress_exposure;  /*  compress  Expose  events  for  widget*/ 
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Boolean  compress_enter leave;  /* 
Boolean  visible_interest;  /* 
XtWidgetProc  destroy;  /* 
XtWidgetProc  resize;  /* 

XtExposeProc  expose;  /* 

XtSetValuesFunc  set_values;  /* 
XtArgsFunc  set_values_hook;  /* 
XtAlmostProc  set_values_almost; /* 
XtArgsProc  get_values_hook;  /* 
XtAcceptFocusProc  accept_focus; /* 
XtVersionType  version;  /* 
XtPointer  callback_private;  /* 
String  tm_table;  /* 

XtGeometryHandler  query_geometry; 
XtStringProc  display_accelerator; 
XtPointer  extension;  /* 

}  CoreClassPart; 


compress  enter  and  leave  events  *, 
select  for  VisibilityNotify  */ 
free  data  for  subclass  pointers  *, 
geom  manager  changed  widget  size  • 
redisplay  window  */ 
set  subclass  resource  values  */ 
notify  that  set_values  called  */ 
set  values  got  "Almost"  geo  reply 


notify  that  get_values  called 
assign  input  focus  to  widget  * 
version  of  Intrinsics  used  */ 
list  of  callback  offsets  */ 
state  machine  */ 
/*  return  preferred  geometry  */ 
/*  display  your  accelerator  */ 
pointer  to  extension  record  */ 


All  widget  classes  have  the  core  class  fields  as  their  first  component.  The  prototypical 
widgetClass  is  defined  with  only  this  set  of  fields.  Various  routines  can  cast  widget  class 
pointers,  as  needed,  to  specific  widget  class  types,  for  example: 

typedef  struct  { 

CoreClassPart  core_class; 
}  WidgetClassRec,  *WidgetClass,  CoreClassRec,  *CoreWidgetClass; 


The  core  instance  record  is  defined  as  follows: 

typedef  struct  _CorePart  { 

Widget  self;  /* 

WidgetClass  widget_class;  /* 

Widget  parent;  /* 

XrmName  xrm_name;  /* 

Boolean  being_destroyed;  /* 
XtCallbackList  destroy_callbacks; / 

XtPointer  constraints;  /* 

Position  x,  y;  /* 

Dimension  width,  height;  /* 

Dimension  border_width;  /* 

Boolean  managed;  /* 

Boolean  sensitive;  /* 

Boolean  ancestor_sensitive;  /* 

XtEventTable  event_table;  /* 

XtTMRec  tm;  /* 

XtTranslations  accelerators;  /* 

Pixel  border_pixel;  /* 

Pixmap  border_pixmap;  /* 

WidgetList  popup_list;  /* 

Cardinal  num_popups;  /* 

String  name;  /* 

Screen  *screen;  /* 


pointer  to  widget  itself  */ 
pointer  to  widget's  ClassRec  */ 
parent  widget  */ 

widget  resource  name  quarkified  */ 
marked  for  destroy  */ 
*  who  to  call  when  widget  destroyed 
constraint  record  */ 
window  position  */ 
window  dimensions  */ 
window  border  width  */ 
is  widget  geometry  managed?  */ 
is  widget  sensitive  to  user  events 


are  all  ancestors  sensitive? 
private  to  event  dispatcher  : 
translation  management  */ 
accelerator  translations  */ 
window  border  pixel  */ 
window  border  pixmap  or  NULL 
list  of  pop  ups  */ 
how  many  pop  ups  */ 
widget  resource  name  */ 
window's  screen  */ 


/ 
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Colormap  colormap; 
Window  window; 
Cardinal  depth; 
Pixel  background_pixel; 
Pixmap  background_pixmap; 
Boolean  visible; 
Boolean  mapped_when_managed; 
}  CorePart; 


/*  colormap  */ 

/*  window  ID  */ 

/*  number  of  planes  in  window  */ 

/*  window  background  pixel  */ 

/*  window  background  pixmap  or  NULL  */ 

/*  is  window  mapped  and  not  occluded?  */ 

/*  map  window  if  it  is  managed?  */ 


All  widget  instances  have  the  core  fields  as  their  first  component.  The  prototypical  type 
widget  is  defined  with  only  this  set  of  fields.  Various  routines  can  cast  widget  pointers,  as 
needed,  to  specific  widget  types. 

typedef  struct  { 
CorePart  core; 
}  WidgetRec,  *Widget,  CoreRec,  *CoreWidget; 

The  core  fields  are  filled  in  by  the  Core  resource  list  and  the  Core  initialize  method.  The 
default  values  for  the  core  fields  are  as  follows: 


Field 


Default  Value 


self 
widget_class 

parent 
xrm_name 

being_destroyed 

destroy_callbacks 

constraints 

x 

y 

width 

height 

border_width 

managed 

sensitive 

ancestor_sensitive 

event_table 

tm 

accelerators 

border_pixel 

border_pixmap 

popup_list 

num_popups 


Address  of  the  widget  structure  (may  not  be  changed). 

widget_class  argument  to  XtCreateWidget  (may  not  be 

changed). 

parent  argument  to  XtCreateWidget  (may  not  be  changed). 

Encoded  name  argument  to  XtCreateWidget  (may  not  be 

changed). 

Parent's  being_destroyed  value. 

NULL 
NULL 

0 
0 
0 
0 

1 

False 

True 

Bitwise  AND  of  parent's  sensitive  and  ancestor_sensi- 

ti  ve. 

Initialized  by  the  Event  Manager. 
Initialized  by  the  Resource  Manager. 

NULL 

XtDefaultForeground 
XtUnspecif iedPixmap 
NULL 

0 
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name 
screen 

colormap 

window 

depth 

background_pixel 

background_pixmap 

visible 

mapped  when_managed 


Default  Value 


name  argument  to  xtcreatewidget  (may  not  be  changed). 
Parent's  screen;  top-level  widget  gets  it  from  display  specifier 
(may  not  be  changed). 
Default  colormap  for  the  screen. 

NULL 

Parent's  depth;  top-level  widget  gets  root  window  depth. 

XtDefaultBackground 
XtUnspecif iedPixmap 
True 

True 


XtUnspecif  iedPixmap  is  a  symbolic  constant  guaranteed  to  have  a  value  different  from 
any  valid  Pixmap  ID,  None,  or  ParentRelative. 

Resources 

The  resource  names,  classes,  and  representation  types  specified  in  the  Core  resource  list  are: 


Name 

Class 

Representation 

Default 

Access 

XtNaccelerators 

XtCAccelerators 

XtRAcceler- 

NULL 

CSG 

atorTable 

XtNbackground 

XtCBackground 

XtRPixel 

White 

CSG 

XtNbackgroundPixmap 

XtCPixmap 

XtRPixmap 

XtUnspeci  f  ied 

CSG 

Pixmap 

XtNborderColor 

XtCBorderColor 

XtRPixel 

Black 

CSG 

XtNborderPixmap 

XtCPixmap 

XtRPixmap 

XtUnspeci  f  ied 

CSG 

Pixmap 

XtNcolormap 

XtCColormap 

XtRColormap 

CopyFromParent 

CG 

XtNdepth 

XtCDepth 

XtRInt 

CopyFromParent 

CG 

XtNmappedWhenManaged 

XtCMappedWhen- 

XtRBoolean 

True 

CSG 

Managed 

XtNscreen 

XtCScreen 

XtRScreen 

XtCopyScreen 

CG 

XtNtranslations 

XtCTranslations 

XtRTrans- 

NULL 

CSG 

lationTable 

For  practical  purposes,  the  following  resources,  inherited  from  Object  and  RectObj,  can  be  con 
sidered  part  of  the  Core  resource  set 


Name 

Class 

Representation 

Default 

Access 

XtNancestorSensitive 

XtCSensitive 

XtRBoolean 

True 

G 

XtNborderWidth 

XtCBorderWidth 

XtRDimension 

1 

CSG 

XtNdestroyCallback 

XtCCallback 

XtRCallback 

NULL 

C 

XtNheight 

XtCHeight 

XtRDimension 

0 

CSG 

XtNsensitive 

XtCSensitive 

XtRBoolean 

True 

CSG 
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Name 

Class 

Representation 

Default 

Access 

XtNwidth 

XtCWidth 

XtRDimension 

0 

CSG 

XtNx 

XtCPosition 

XtRPosition 

0 

CSG 

XtNy 

XtCPosition 

XtRPosition 

0 

CSG 

Core  Methods 

Core  methods  can  often  be  inherited  from  a  superclass.  This  is  done  by  specifying  xt- 
Inheritproc/ja/ne  in  the  class  field.  For  example,  xtlnheritRealize  will  inherit  the 
realize  method.  All  Core  methods  are  described  in  reference  pages  in  Section  4. 

See  Also 

Core(3),  Object (3),  RectObjQ), 

class jnitialize(4\  class_part_initialize(4\  destroy(4),  display _accelerator (4),  expose(4), 
get_values_hook(4\  initialize^),  initialize  _hook(4\  query_geometry(4),  realize(4),  resize(4), 
set_values(4),  set_values_almost(4),  set_values_hook(4). 
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f  Object 


Name 

Object  class  —  base  class  encapsulating  resource  management  and  callbacks. 

Synopsis 

#include  <Xll/StringDef s .h> 
#include  <Xll/Intrinsic .h> 

The  opaque  types  Object  and  Ob  jectClass  and  the  opaque  variable  ob  jectClass  are 
defined  for  generic  actions  on  objects. 

The  Object  class  is  not  normally  instantiated  directly. 

Class  Hierarchy 

Object 

Description 

The  Object  class  contains  the  definitions  of  fields  common  to  all  objects.  It  encapsulates  the 
mechanisms  for  resource  management.  All  objects  and  widgets  are  subclasses  of  Object,  which 
is  defined  by  the  ObjectClassPart  and  ObjectPart  structures. 

The  Object  class  was  made  public  in  R4  to  enable  programmers  to  use  the  Intrinsics  classing 
and  resource  handling  mechanisms  for  things  besides  widgets.  Objects  make  many  common 
uses  of  subresources  obsolete. 

Composite  widget  classes  that  wish  to  accept  non-widget  children  must  set  the 
accept s_objects  field  in  the  CompositeClassExtension  structure  to  True.  Xt- 
CreateWidget  will  otherwise  generate  an  error  message  on  an  attempt  to  create  a  non- 
widget  child. 

Of  the  classes  defined  by  the  Intrinsics,  only  ApplicationShell  accepts  non- widget  children,  and 
the  class  of  any  non-widget  child  must  not  be  rectOb  jClass  or  any  subclass.  The  intent  of 
allowing  Object  children  of  ApplicationShell  is  to  provide  clients  a  simple  mechanism  for 
establishing  the  resource  naming  root  of  an  object  hierarchy. 

ObjectClassPart  Structure 

The  common  fields  for  all  object  classes  are  defined  in  the  ObjectClassPart  structure.  All 
fields  have  the  same  purpose  and  function  as  the  corresponding  fields  in  CoreClassPart; 
fields  whose  names  are  objrt  for  some  integer  n  are  not  used  for  Objects,  but  exist  to  pad  the 
data  structure  so  that  it  matches  Core's  class  record.  The  class  record  initialization  must  fill  all 
objn  fields  with  NULL  or  zero  as  appropriate  to  the  type. 

typedef  struct  _0b jectClassPart  { 
WidgetClass  superclass; 
String  class_name; 
Cardinal  widget_size; 
XtProc  class_initialize; 
XtWidgetClassProc  class_part_initialize; 
XtEnum  class_inited; 
XtlnitProc  initialize; 
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XtArgsProc  initialize_hook; 
XtProc  objl; 
XtPointer  obj2; 
Cardinal  obj3; 
XtResourceList  resources; 
Cardinal  num_resources; 
XrmClass  xrm_class; 
Boolean  obj4; 
XtEnum  obj5; 
Boolean  obj6; 
Boolean  obj7; 
XtWidgetProc  destroy; 
XtProc  obj8; 
XtProc  obj9; 

XtSetValuesFunc  set_values; 
XtArgsFunc  set_values_hook; 
XtProc  objlO; 

XtArgsProc  get_values_hook; 
XtProc  objll; 
XtVersionType  version; 
XtPointer  callback_private; 
String  obj!2; 
XtProc  obj!3; 
XtProc  obj!4; 
XtPointer  extension; 
}  ObjectClassPart; 

The  prototypical  Ob  jectClass  consists  of  just  the  ObjectClassPart. 

typedef   struct  _0b jectClassRec    { 

ObjectClassPart   ob ject_class; 
}    ObjectClassRec,    *0b jectClass; 

,,f 
The  predefined  class  record  and  pointer  for  Ob  jectClassRec  are: 

extern  ObjectClassRec  ob jectClassRec; 
extern  WidgetClass  objectClass; 

ObjectPart  Structure 

The  common  fields  for  all  object  instances  are  defined  in  the  ObjectPart  structure.   All 
fields  have  the  same  meaning  as  the  corresponding  fields  in  CorePart. 

typedef  struct  _ObjectPart  { 

Widget  self; 

WidgetClass  widget_class; 

Widget  parent; 

XrmName  xrm_name; 

Boolean  being_destroyed; 

XtCallbackList  destroy_callbacks; 

XtPointer  constraints; 
}  ObjectPart; 
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All  object  instances  have  the  Object  fields  as  their  first  component.  The  prototypical  type 
Object  is  defined  with  only  this  set  of  fields.  Various  routines  can  cast  object  pointers,  as 
needed,  to  specific  object  types. 

typedef  struct  _ObjectRec  { 

ObjectPart  object; 
}  ObjectRec,  *0bject; 

Resources 

The  resource  names,  classes,  and  representation  types  specified  in  the  Object  resource  list  are: 


Name 

Class 

Representation 

Default 

Access 

XtNdestroyCallback 

XtCCallback 

XtRCallback 

NULL 

c 

ObjectPart  Default  Values 

All  fields  in  ObjectPart  have  the  same  default  values  as  the  corresponding  fields  in  Core- 
Part. 

Object  Arguments  To  Xt  Intrinsics  Routines 

Starting  in  R4,  the  WidgetClass  arguments  to  the  following  procedures  may  be  ob  jectClass 
or  any  subclass: 

•  XtlnitializeWidgetClass.XtCreateWidget.XtVaCreateWidget 

•  XtIsSubclass,XtCheckSubclass 

•  XtGetResourceList,  XtGetConstraintResourceList 

The  Widget  arguments  to  the  following  procedures  may  be  of  class  Object  or  any  subclass: 
XtCreateWidget, XtVaCreateWidget 

XtAddCallback,  XtAddCallbacks,  XtRemoveCallback,  XtRemoveCall- 
backs,  XtRemoveAllCallbacks,  XtCallCallbacks,  XtHasCallbacks,  Xt- 
CallCallbackList 

•  XtClass,  XtSuperclass,  XtlsSubclass,  XtCheckSubclass,  XtlsObject, 
XtlsRectObj,  XtlsWidget,  XtlsComposite,  XtlsConstraint,  XtlsShell, 
XtlsOverrideShell,  XtlsWMShell,  XtlsVendorShell,  XtlsTransient- 
Shell,XtIsToplevelShell,XtIsApplicationShell. 

•  XtlsManaged,  XtlsSensitive 

(both  will  return  False  if  argument  is  not  a  subclass  of  RectOb  j) 

•  XtlsRealized 

(returns  the  state  of  the  nearest  windowed  ancestor  if  argument  is  not  of  a  subclass  of 
Core) 

•  XtWidgetToApplicationContext 
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•  XtDestroyWidget 

•  XtDisplayOf Ob ject, XtScreenOf Ob ject, XtWindowOf Ob ject 

•  xtSetKeyboardFocus  (descendant) 
XtGetGC, XtReleaseGC 
XtNameToWidget,  XtName 

XtSetValues,  XtGetValues,  XtVaSetValues,  XtVaGetValues,  XtGet- 
Subvalues, XtVaGetSubvalues 

•  XtGetSubresources,    XtGetApplicationResources,    XtVaGetSub- 
resources.XtVaGetApplicationResources 

•  XtConvert,XtConvertAndStore 

The  return  value  of  the  following  procedures  will  be  of  class  Object  or  a  subclass: 
XtCreateWidget, XtVaCreateWidget 

•  XtParent 

•  XtNameToWidget 

The  return  value  of  the  following  procedures  will  be  ob  jectClass  or  a  subclass: 

•  XtClass.XtSuperclass 

Methods 

Object  declares  some  of  the  methods  used  by  Core.  See  Section  4  for  reference  pages  about 
these  methods. 
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Name 

OverrideShell  widget  class  —  pop-up  shell  that  bypasses  window  management. 

Synopsis 

#include  <Xll/StringDefs .h> 

|#include  <Xll/Intrinsic .h> 
widget  =  XtCreatePopupShell (name,  overrideShellWidgetClass,  .  .  . ) 

Class  Hierarchy 

Core  -»  Composite  ->  Shell  ->  OverrideShell 

Description 

I         The  OverrideShell  widget  class  is  a  direct  subclass  of  Shell  that  is  used  for  pop-up  widgets  that 
bypass  window-manager  interaction  (such  as  pop-up  menus). 

Class  and  Instance  Structures 

The  OverrideShellClassPart  contains  no  additional  class  fields.    Its  declaration  in 
<Xll/ShellP.h>  is  similar  to  those  of  the  other  shells: 

typedef   struct    { 

XtPointer   extension;         /*   pointer   to   extension   record    */ 
}    OverrideShellClassPart; 

The  extension  field  is  NULL. 

The  instance  structure,  OverrideShellPart,  is  declared  as  follows: 

typedef  struct  { 

int  empty; 
}  OverrideShellPart; 

Resources 

Override  shells  have  no  resources  other  than  those  inherited  from  superclasses. 
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Name 

RectObj  class  —  base  class  encapsulating  geometry  management. 

Synopsis 

tinclude   <Xll/StringDefs . h> 
#include   <Xll/Intrinsic .h> 

The  opaque  types  RectObj  and  RectOb  jClass  and  the  opaque  variable  rectOb  jciass  are 
defined  for  generic  actions  on  objects  that  are  a  subclass  of  RectObj. 

The  RectObj  class  is  not  normally  instantiated  directly. 

Class  Hierarchy 
Object  ->  RectObj 

Description 

Rectangle  objects  are  a  subclass  of  Object  that  represent  rectangular  areas.  They  encapsulate 
the  mechanisms  for  geometry  management,  and  are  called  RectObj  to  avoid  conflict  with  the 
Xlib  Rectangle  data  type. 

RectObj  can  be  subclassed  to  provide  widget-like  objects  (sometimes  called  "gadgets")  that  do 
not  use  windows  and  that  do  not  have  features  often  unused  in  simple  widgets.  This  can  save 
memory  resources  both  in  the  server  and  in  applications. 

In  the  following  discussion,  "RectObj"  refers  only  to  objects  that  are  a  subclass  of  RectObj  and 
that  are  not  a  subclass  of  Core. 

Composite  widget  classes  that  wish  to  accept  RectObj  children  must  set  the 
accepts_objects  field  in  the  CompositeClassExtension  extension  structure  to 
True.  XtCreateWidget  or  XtCreateManagedWidget  will  otherwise  generate  an  error 
if  called  to  create  a  non-widget  child. 

If  the  Composite  widget  supports  children  only  of  class  RectObj  or  of  a  subclass  (i.e.,  not  gen 
eral  Objects),  it  must  declare  an  insert_child  method  and  check  the  subclass  of  each  new 
child  in  that  method.  None  of  the  classes  defined  by  the  Intrinsics  accept  RectObj  children. 

If  gadgets  are  defined  in  an  object  set,  the  parent  is  responsible  for  much  more  than  the  parent 
of  a  widget  The  parent  must  request  and  handle  input  events  that  occur  for  the  gadget.  The 
parent  is  also  responsible  for  making  sure  that  when  it  receives  an  expose  event,  the  gadget 
children  get  drawn  correctly.  Subclasses  of  RectObj  have  expose  procedures,  but  the  parent  is 
free  to  ignore  them,  instead  drawing  the  contents  of  the  child  itself.  This  can  potentially  save 
graphics  context  switching.  The  precise  contents  of  the  Expose  event  and  Region  argu 
ments  to  the  RectObj  expose  procedure  are  not  specified  by  the  Intrinsics;  a  particular  rectangle 
object  is  free  to  define  not  only  the  coordinate  system  origin  (self-relative  or  parent-relative) 
but  also  whether  the  rectangle,  the  Region,  or  both  are  assumed  to  have  been  intersected  by  the 
visible  region  of  the  object. 

Normally,  a  composite  widget  that  accepts  non-widget  children  documents  those  children  it  can 
handle,  since  a  gadget,  unlike  a  widget,  cannot  be  viewed  as  a  completely  self-contained 
entity.  Since  a  particular  composite  widget  class  is  usually  designed  to  handle  gadgets  of  only 
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a  limited  set  of  classes,  it  should  check  the  classes  of  newly  added  children  in  its 
insert_child  method  to  make  sure  that  it  can  deal  with  them. 

The  Intrinsics  will  clear  areas  of  a  parent  window  obscured  by  RectObj  children,  causing 
Expose  events,  under  the  following  circumstances: 

•  A  RectObj  child  is  managed  or  unmanaged. 

•  In  a  call  to  XtSetValues  on  a  RectObj  child,  one  or  more  of  the  set_values  meth 
ods  returns  True. 

•  In  a  call  to  XtConf  igureWidget  on  a  RectObj  child,  areas  will  be  cleared  corre 
sponding  to  both  the  old  and  the  new  child  geometries,  including  the  border,  if  the  geom 
etry  changes. 

•  In  a  call  to  xtMoveWidget  on  a  RectObj  child,  areas  will  be  cleared  corresponding  to 
both  the  old  and  the  new  child  geometries,  including  the  border,  if  the  geometry  changes. 

•  In  a  call  to  xtResizeWidget  on  a  RectObj  child,  an  single  rectangle  will  be  cleared 
corresponding  to  the  larger  of  the  old  and  the  new  child  geometries,  if  they  are  different. 

•  In  a  call  to  XtMakeGeometryRequest  (or  XtMakeResizeRequest)  on  a  Rect 
Obj,  if  the  manager  returns  xtGeometryYes,  two  rectangles  will  be  cleared  corre 
sponding  to  both  the  old  and  the  new  child  geometries. 

Stacking  order  is  not  supported  for  RectObjs.  If  the  child  geometries  overlap,  Composite  widg 
ets  with  RectObj  children  can  define  any  semantics  desired,  including  making  this  an  error. 

When  a  RectObj  is  playing  the  role  of  a  widget,  developers  must  be  reminded  to  avoid  making 
assumptions  about  the  object  passed  in  the  widget  argument  to  a  callback  procedure. 

RectObjClassPart  Structure 

As  with  the  Ob  jectClassPart  structure,  all  fields  have  the  same  purpose  and  function  as 
the  corresponding  fields  in  CoreClassPart;  fields  whose  names  are  rectrt  for  some  integer 
n  are  not  used  for  RectObjs  but  exist  to  pad  the  data  structure  so  that  it  matches  Core's  class 
record.  The  class  record  initialization  must  fill  all  rectn  fields  with  NULL  or  zero  as  appropri 
ate  to  the  type. 

typedef  struct  _RectOb jClassPart  { 
WidgetClass  superclass; 
String  class_name; 
Cardinal  widget_size; 
XtProc  class_initialize; 

XtWidgetClassProc  class_part_initialize; 
XtEnum  class_inited; 
XtlnitProc  initialize; 
XtArgsProc  initialize_hook; 
XtProc  rectl; 
XtPointer  rect2; 
Cardinal  rect3; 
XtResourceList  resources; 
Cardinal  num  resources; 
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XrmClass   xrm_class; 
Boolean   rect4; 
XtEnum   rectS; 
Boolean   rect6; 
Boolean   rect7; 
XtWidgetProc   destroy; 
XtWidgetProc   resize; 
XtExposeProc   expose; 
XtSetValuesFunc   set_values; 
XtArgsFunc   set_values_hook; 
XtAlmostProc   set_values_almost; 
XtArgsProc   get_values_hook; 
XtProc   rect9; 
XtVersionType   version; 
XtPointer  callback_private; 
String   rectlO; 

XtGeometryHandler   query_geometry; 
XtProc   rectll; 
XtPointer   extension    ; 
}    RectObjClassPart; 

The  RectObj  class  record  consists  of  just  the  RectObjClassPart: 

typedef   struct   _RectOb jClassRec    { 

RectObjClassPart    rect_class; 
}    RectObjClassRec,     *RectOb jClass; 

The  predefined  class  record  and  pointer  for  RectObjClassRec  are: 

extern  RectObjClassRec  rectOb JClassRec; 
extern  WidgetClass  rectOb jClass; 

RectObjPart  Structure 

In  addition  to  the  Ob  jectPart  fields,  RectObj  objects  have  the  following  fields  defined  in  the 
RectObjPart  structure.  All  fields  have  the  same  meaning  as  the  corresponding  field  in 
CorePart. 

typedef  struct  _RectObjPart  { 

Position  x,  y; 

Dimension  width,  height; 

Dimension  border_width; 

Boolean  managed; 

Boolean  sensitive; 

Boolean  ancestor_sensitive; 
}  RectObjPart; 

RectObj  objects  have  the  rectangle  fields  immediately  following  the  object  fields: 

typedef  struct  _RectObjRec  { 

ObjectPart  object; 

RectObjPart  rectangle; 
}  RectObjRec; 
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Resources 

RectObjs  have  the  following  resources  in  addition  to  those  inherited  from  the  Object  class: 


Name 

Class 

Representation 

Default 

Access 

XtNancestorSensitive 

XtCSensitive 

XtRBoolean 

True 

G 

XtNborderWidth 

XtCBorderWidth 

XtRDimension 

1 

CSG 

XtNheight 

XtCHeight 

XtRDimension 

0 

CSG 

XtNsensitive 

XtCSensitive 

XtRBoolean 

True 

CSG 

XtNwidth 

XtCWidth 

XtRDimension 

0 

CSG 

XtNx 

XtCPosition 

XtRPosition 

0 

CSG 

XtNy 

XtCPosition 

XtRPosition 

0 

CSG 

RectObjPart  Default  Values 

All  fields  in  RectObjPart  have  the  same  default  values  as  the  corresponding  fields  in 
CorePart. 

RectObj  Arguments  To  Intrinsics  Routines 

The  widgetClass  arguments  to  the  following  functions  may  be  rectOb  jClass  or  any 
subclass: 

•  XtCreateManagedWidget, XtVaCreateManagedWidget 

The  widget  arguments  to  the  following  functions  may  be  of  class  RectObj  or  any  subclass: 

•  XtConf  igureWidget,  XtMoveWidget,  XtResizeWidget 

•  XtMakeGeometryRequest, XtMakeResizeRequest 

XtManageChildren,  XtManageChild,  XtUnmanageChildren,  XtUnmanage- 
Child 

•  XtQueryGeometry 
XtSetSensitive 

•  XtTranslateCoords 

The  return  value  of  the  following  functions  will  be  of  class  RectObj  or  a  subclass: 

•  XtCreateManagedWidget,  XtVaCreateManagedWidget 

Methods 

RectObj  declares  some  of  the  methods  used  by  Core.  See  Section  4  for  reference  pages  about 
these  methods. 
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Name 

Shell  widget  class  —  top-level  widget  that  handles  application/window  manager  interaction. 

Synopsis 

tfinclude  <Xll/StringDef s . h> 
#include  <Xll/Intrinsic .h> 

The  following  opaque  types  and  opaque  variables  are  defined  for  generic  operations  on  widgets 
that  are  a  subclass  of  ShellWidgetClass: 


Types 


ShellWidget 

OverrideShellWidget 

WMShellWidget 

VendorShellWidget 

Transient ShellWidget 

TopLevelShellWidget 

Application She 11 Widget 


Variables 


ShellWidgetClass 
OverrideShellWidget Class 
wmShe 11 Widget Class 
vendor ShellWidget Class 
transient ShellWidget Class 
topLevelShellWidget Class 
applicationShellWidget Class 
ShellWidgetClass 
OverrideShellWidget Class 
WMShellWidgetClass 
VendorShellWidgetClass 
Transient ShellWidgetClass 
TopLevelShellWidget Class 
ApplicationShellWidget Class 


The  Shell  widget  class  is  usually  not  instantiated  directly.  See  the  reference  pages  for  the  sub 
classes  OverrideShell,  TransientShell,  TopLevelShell,  and  Applications  hell  for  information  on 
Shell  widget  instantiation. 

*-' 
Class  hierarchy 

Core  — >  Composite  -»  Shell 

Description 

Widgets  negotiate  their  size  and  position  with  their  parent  widget  (i.e.,  the  widget  that  directly 
contains  them).  Widgets  at  the  top  of  the  hierarchy  do  not  have  parent  widgets.  Instead,  they 
must  deal  with  the  outside  world.  To  provide  for  this,  each  top-level  widget  is  encapsulated  in 
a  special  widget,  called  a  Shell. 

Shell  widgets,  a  subclass  of  the  Composite  widget,  encapsulate  other  widgets  and  can  allow  a 
widget  to  avoid  the  geometry  clipping  imposed  by  the  parent/child  window  relationship.  They 
also  can  provide  a  layer  of  communication  with  the  window  manager. 

Shells  have  been  designed  to  be  as  nearly  invisible  as  possible.  Clients  have  to  create  them  (the 
top-level  widget  returned  by  a  call  to  XtAppInitialize  or  XtCreateApplicat ion- 
Con  text  is  a  Shell  widget,  as  is  a  pop-up  widget  created  with  xt Popup),  but  they  should 
never  have  to  worry  about  their  sizes. 
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Shell 


If  a  shell  widget  is  resized  from  the  outside  (typically  by  a  window  manager),  the  shell  widget 
also  resizes  its  child  widget  automatically.  Similarly,  if  the  shell's  child  widget  needs  to 
change  size,  it  can  make  a  geometry  request  to  the  shell,  and  the  shell  negotiates  the  size 
change  with  the  outer  environment.  Clients  should  never  attempt  to  change  the  size  of  their 
shells  directly. 

There  are  seven  different  types  of  shells.  Only  four  of  these  are  public  (i.e.,  should  be  instan 
tiated  by  applications): 

OverrideShell  Used  for  shell  windows  that  completely  bypass  the  window  manager 

(for  example,  pop-up  menu  shells).  A  subclass  of  Shell  (see  below). 


TransientShell 


TopLevelShell 


ApplicationShell 


Used  for  shell  windows  that  can  be  manipulated  by  the  window 
manager  but  are  not  allowed  to  be  iconified  separately  (for  example, 
Dialog  boxes  that  make  no  sense  without  their  associated  applica 
tion).  They  are  iconified  by  the  window  manager  only  if  the  main 
application  shell  is  iconified.  A  subclass  of  Vendors  hell  (see 
below). 

Used  for  normal  top-level  windows  (for  example,  any  additional  top- 
level  widgets  an  application  needs).  A  subclass  of  VendorShell  (see 
below). 


Used  by  the  window  manager  to  define  a  separate  application 
instance,  which  is  the  main  top-level  window  of  the  application.  A 
subclass  of  TopLevelShell. 

Three  classes  of  shells  are  internal  and  should  not  be  instantiated  or  subclassed: 


Shell 

WMShell 

VendorShell 


Provides  the  base  class  for  shell  widgets  and  the  fields  needed  for  all 
types  of  shells.  Shell  is  a  direct  subclass  of  Composite. 

Contains  fields  needed  by  the  common  window  manager  protocol 
and  is  a  subclass  of  Shell. 

Contains  fields  used  by  vendor-specific  window  managers  and  is  a 
subclass  of  WMShell. 
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Figure  1  shows  the  class  hierarchy  for  Shell  widgets. 


Shell 


WMShell     I        lOverrideShellj 


VendorShell  | 


j I 


TopLevelShell    I       TransientShell 


ApplicationShell  | 


Figure  1.  Class  Hierarchy  for  Shell  widget  classes 

The  actual  definitions  for  all  of  the  Shell  subclasses  are  in  <X1  II  Shell. h>,  <Xll/ShellP.h>, 
<XlllVendor.h>  and  <XlllVendorP.h>.  Only  <XlllShell.h>  needs  to  be  routinely  included  in 
application  code,  since  it  defines  the  class  variables  for  the  four  Shell  classes  that  are  usually 
instantiated,  namely  applicationShellWidgetClass,  overrideShellWidget- 
Class, topLevelShellWidgetClass  and  transientShellWidgetClass. 

This  manual  page  describes  the  internals  of  the  Shell  widget  class  proper.  See  the  separate 
pages  for  each  of  the  other  Shell  classes  for  more  information. 

Class  Structures 

The  Shell  widget  class  and  all  of  its  subclasses  have  the  same  class  part: 

typedef  struct  { 

XtPointer  extension;    /*pointer  to  extension  record  */ 

}  ShellClassPart; 

The  extension  field  is  NULL,  except  in  the  Shell  class  proper,  where  it  is  a  pointer  to  a 
ShellClassExtensionRec,  which  is  defined  as  follows: 

typedef  struct  { 

XtPointer  next_extension; 

XrmQuark  record_type; 

long  version; 

Cardinal  record_size; 

XtGeometryHandler  root_geometry_manager; 
}  ShellClassExtensionRec,  *ShellClassExtension; 
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The  general  format  for  Class  Extension  Records  is  described  in  Introduction(3).  The  details 
specific  to  the  Shell  class  are  as  follows: 

The  symbolic  constant  for  the  ShellClassExtension  version  ID  is  xtShell- 
ExtensionVersion 

The  root_geometry_manager  field  specifies  a  procedure  that  acts  as  the  parent  geometry 
manager  for  geometry  requests  made  by  shell  widgets.  When  a  shell  widget  calls  xtMake- 
GeometryRequest  or  XtMakeResizeRequest,  the  root_geometry_manager 
method  is  invoked  to  negotiate  the  new  geometry  with  the  window  manager 

•  If  the  window  manager  permits  the  new  geometry,  then  the  root_geometry_manager 
should  return  Xt  Geometry  Yes. 

•  If  the  window  manager  denies  the  geometry  request  or  does  not  change  the  window  geom 
etry  within  some  timeout  interval  (equal  to  wm_timeout  in  the  case  of  WMShells),  then 
the  root_geometry_manager  should  return  XtGeometryNo. 

•  If  the  window  manager  makes  some  alternate  geometry  change,  then  the  root_geome- 
try_manager  may  either  return  XtGeometryNo  and  handle  the  new  geometry  as  a 
resize,  or  root_geometry_manager  may  return  XtGeometryAlmost  in  anticipat 
ion  that  the  shell  will  accept  the  compromise.  If  the  compromise  is  not  accepted,  the  new 
size  must  then  be  handled  as  a  resize. 

Subclasses  of  Shell  that  wish  to  provide  their  own  root_geometry_manager  should  use 
enveloping  to  invoke  their  superclass'  root_geometry_manager  under  most  situations, 
since  the  window  manager  interaction  may  be  very  complex. 

If  no  ShellClassPart  extension  record  is  declared  with  record_type  equal  to 
NULLQUARK,  then  XtlnheritRootGeometryManager  is  assumed. 

The  Class  Parts  are  combined  into  the  complete  class  record  by  placing  the  (empty)  shell  fields 
immediately  following  the  Composite  fields.  The  following  declarations  show  the  complete 
class  records  for  all  of  the  shells  in  turn: 

typedef  struct  _ShellClassRec  { 

CoreClassPart  core_class; 

Compos iteClassPart        compos it e_class; 

ShellClassPart  shell_class; 

}  ShellClassRec; 

typedef  struct  _OverrideShellClassRec  { 

CoreClassPart  core_class; 

Compos iteClassPart        compos it e_class; 

ShellClassPart  shell_class; 

OverrideShellClassPart    override_shell_class; 
}  OverrideShellClassRec; 
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typedef  struct  _WMShellClassRec  { 

CoreClassPart 

Compos iteClassP art 

ShellClassPart 

WMShellClassPart 
}  WMShellClassRec; 


core_class; 
composite_class; 
shell_class; 
wm_she 1 l_c lass; 


typedef  struct   VendorShellClassRec  { 


CoreClassPart 
Compos iteC la ssPart 
ShellClassPart 
WMShellClassPart 
VendorShellClassPart 
}  VendorShellClassRec; 


core_class; 
composite_class; 
shell_class; 
wm_shell_class; 
vendor  shell  class. 


typedef  struct  _TransientShellClassRec  { 


CoreClassPart 
Compos iteC la ssP art 
ShellClassPart 
WMShellClassPart 
VendorShellClassPart 
Transient ShellClassPart 
}  TransientShellClassRec; 


core_class; 

compos ite_c lass; 

shell_class; 

wm_shell_class; 

vendor_shell_class; 

transient  shell  class, 


typedef  struct  _ApplicationShellClassRec  { 


CoreClassPart 
CompositeClassPart 
ShellClassPart 
WMShellClassPart 
VendorShellClassPart 
TopLevelShellClassPart 
ApplicationShellClassPart  application_shell_class, 
}  ApplicationShellClassRec; 


core_class; 

composite_class; 

shell_class; 

wm_shell_class; 

vendor_shell_class; 

top  level_shell_class; 


The  predefined  class  records  and  pointers  for  shells  are: 


extern  ShellClassRec 

extern  OverrideShellClassRec 

extern  WMShellClassRec 

extern  VendorShellClassRec 

extern  TransientShellClassRec 

extern  TopLevelShellClassRec 

extern  ApplicationShellClassRec 


extern 
extern 
extern 
extern 
extern 
extern 
extern 


WidgetClass 
WidgetClass 
WidgetClass 
WidgetClass 
WidgetClass 
WidgetClass 
WidgetClass 


ShellClassRec; 

OverrideShellClassRec; 

wmShellClassRec; 

VendorShellClassRec; 

transientShellClassRec; 

topLevelShellClassRec; 

applicationShellClassRec; 

shellWidgetClass; 

over ride She HWidget Class  ; 

wmShe  HWidget  Class  ; 

vendorShel IWidget Class ; 

t  ransient  She  HWidget  Class  ; 

topLevelShellWidget Class ; 

applicationShel IWidget Class, 
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Shell  Instance  Part 

The  Shell  widget  class  has  the  following  additional  fields  defined  in  its  instance  part: 

typedef  struct  { 

String  geometry; 

XtCreatePopupChildProc  create_popup_child_proc; 

XtGrabKind  grab_kind; 

Boolean  spring_loaded; 

Boolean  popped_up; 

Boolean  allow_shell_resize; 

Boolean  client_specif led; 

Boolean  save_under; 

Boolean  override_redirect; 

XtCallbackList  popup_callback; 

XtCallbackList  popdown_callback; 
}  ShellPart; 

The  instance  parts  for  all  of  the  other  Shell  subclasses  are  defined  as  follows  (see  the  relevant 
reference  pages  for  further  details): 

typedef  struct  {  int  empty;  }  OverrideShellPart; 

typedef  struct  { 

String  title; 

int  wm_timeout; 

Boolean  wait_for_wm; 

Boolean  transient; 

XSizeHints  size_hints; 

XWMHints  wm_hints; 
}  WMShellPart; 

typedef  struct  { 

int  vendor_specif ic; 
}  VendorShellPart; 

typedef  struct  {  int  empty;  }  TransientShellPart ; 

typedef  struct  { 

String  icon_name; 

Boolean  iconic; 
}  TopLevelShellPart; 

typedef  struct  { 

char  *class; 

XrmClass  xrm_class; 

int  argc; 

char  **argv; 
}  ApplicationShellPart; 
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The  full  definitions  of  the  various  shell  widgets  have  shell  fields  following  composite  fields: 

typedef  struct  { 

CorePart  core; 

CompositePart  composite; 

ShellPart  shell; 
}  ShellRec,  *ShellWidget; 

typedef  struct  { 

CorePart  core; 

CompositePart  composite; 

ShellPart  shell; 

OverrideShellPart  override; 
}  OverrideShellRec,  *OverrideShellWidget; 

typedef  struct  { 

CorePart  core; 

CompositePart  composite; 

ShellPart  shell; 

WMShellPart  wm; 
}  WMShellRec,  *WMShellWidget ; 

typedef  struct  { 

CorePart  core; 

CompositePart  composite; 

ShellPart  shell; 

WMShellPart  wm; 

VendorShellPart  vendor; 
}  VendorShellRec,  *VendorShellWidget ; 

typedef  struct  { 

CorePart  core; 

CompositePart  composite; 

ShellPart  shell; 

WMShellPart  wm; 

VendorShellPart  vendor; 

TransientShellPart  transient; 
}  TransientShellRec,  *TransientShellWidget; 

typedef  struct  { 

CorePart  core; 

CompositePart  composite; 

ShellPart  shell; 

WMShellPart  wm; 

VendorShellPart  vendor; 

TopLevelShellPart  topLevel; 
}  TopLevelShellRec,  *TopLevelShellWidget; 

typedef   struct  { 

CorePart  core; 

CompositePart  composite; 

ShellPart  shell; 

WMShellPart  wm; 
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VendorShellPart      vendor; 
TopLevelShellPart    topLevel; 
ApplicationShellPart  application; 
}  ApplicationShellRec,  *ApplicationShellWidget ; 

Resources 

Shell  widgets  have  the  following  resources  in  addition  to  those  inherited  from  superclasses: 


Name 

Class 

Representation 

Default 

Access 

XtNallowShellResize 

XtCAllowShellResize 

XtRBoolean 

False 

CSG 

XtNcreatePopup- 
ChildProc 

XtCCreatePopup- 
ChildProc 

XtRFunction 

NULL 

CSG 

XtNgeometry 

XtCGeometry 

XtRString 

NULL 

CG 

XtNoverrideRedirect 

XtCOverrideRedirect 

XtRBoolean 

False 

CSG 

XtNpopdownCallback 

XtCCallback 

XtRCallback 

NULL 

C 

XtNpopupCallback 

XtCCallback 

XtRCallback 

NULL 

C 

XtNsaveUnder 

XtCSaveUnder 

XtRBoolean 

False 

CSG 

XtNvisual 

XtCvisual 

XtRVisual 

CopyFrom- 
Parent 

CSG 

ShellPart  Default  Values 

The  default  values  for  the  ShellPart  fields  (common  to  all  classes  of  public  shells,  and  filled 
in  by  the  Shell  resource  lists  and  the  Shell  initialize  methods)  are: 


Field 


Default  Value 


geometry 

creat e_popup_child_proc 

grab_kind 

spring_loaded 

popped_up 

allow_shell_resize 

client_specif ied 

save_under 

override_redirect 

popup_callback 

popdown_callback 


NULL 
NULL 

(internal) 
(internal) 
(internal) 

False 

(internal) 

True  for  Overrides  hell  and  Transients  hell;  False  otherwise 

True  for  OverrideShell;  False  otherwise 

NULL 
NULL 


The  geometry  resource  specifies  the  size  and  position  and  is  usually  done  only  from  a  com 
mand  line  or  a  defaults  file. 

The  create_popup_child_proc  is  called  by  the  xtPopup  procedure  and  is  usually 

NULL. 

The  grab_kind,  spring_loaded,  and  popped_up  fields  maintain  state  information  as 
described  under  XtPopup,  XtMenuPopup,  XtPopdown,  and  xtMenuPopdown. 
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The  allow_shell_resize  field  controls  whether  the  widget  contained  by  the  shell  is 
allowed  to  try  to  resize  itself.  If  allow_shell_resize  is  False,  any  geometry  requests 
always  return  XtGeometryNo. 

Setting  save_under  instructs  the  server  to  attempt  to  save  the  contents  of  windows  obscured 
by  the  shell  when  it  is  mapped  and  to  restore  its  contents  later  automatically.  This  resource  is 
useful  for  pop-up  menus. 

Setting  override_redirect  determines  whether  the  shell  window  is  visible  to  the  window 
manager.  If  this  resource  is  True,  the  window  is  immediately  mapped  without  the  manager's 
intervention.  The  pop-up  and  pop-down  callbacks  are  called  during  xtPopup  and  xt- 
Popdown. 
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Name 

TopLevelShell  widget  class  —  additional  top-level  shell  for  an  application. 

Synopsis 

#include  <Xll/StringDefs.h> 
#include  <Xll/Intrinsic.h> 

widget  =• XtAppCreateShell (appName,  appClass, 

topLevelShellWidgetClass,  .  .  .  ) 


Class  Hierarchy 

Core  — >  Composite 


Shell  ->  WMShell  ->  VendorShell  ->  TopLevelShell 


Description 

The  TopLevelShell  widget  class  is  a  subclass  of  VendorShell  that  is  used  for  alternate  top  level 
windows  in  applications  having  more  than  one  top-level  window  (one  that  serves  as  the  root  of 
a  widget  instance  tree).  An  instance  of  this  widget  class  can  be  created  by  a  call  to  xt- 

CreateApplicationShell. 

Class  and  Instance  Structures 

The  TopLevelShellClassPart  contains  no  additional  class  fields.  Its  declaration  in 
<XlllShellP.h>  is  similar  to  those  of  the  other  shells: 


typedef   struct    { 

XtPointer  extension; 
}    TopLevelShellClassPart; 


/*  pointer  to  extension   record   */ 


The  extension  field  is  NULL. 

The  instance  structure,  TopLevelShellPart,  is  declared  as  follows: 

typedef  struct  { 

String  iconName; 

Boolean  iconic; 

Atom  iconNameEncoding; 
}  TopLevelShellPart; 


Resources 

TopLevelShell  widgets  have  the  following  resources  in  addition  to  those  inherited  from  super 
classes: 


Resource 

Class 

Representation 

Default 

Access 

XtNiconName 

XtCIconName 

XtRString 

Shell  widget's 

CSG 

name 

XtNiconic 

Xtlconic 

XtRBoolean 

False 

CG 

XtNiconNameEncoding 

XtCIconName- 

XtRAtom 

XASTRING 

CSG 

Encoding 
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The  iconName  and  iconNameEncoding  fields  are  stored  in  the  WMICONNAME  property 
on  the  shell's  window  by  the  shell  realize  methods. 

The  iconic  field  may  be  used  by  a  client  to  request  that  the  window  manager  iconify  or  deicon- 
ify  the  shell;  the  TopLevelShell  setvalues  method  will  send  the  appropriate  WMCHANGE- 
STATE  message  (as  specified  by  the  ICCCM)  if  this  resource  is  changed  from  False  to  True 
and  will  call  XtPopup  specifying  grabKind  as  XtGrabNone  if  iconic  is  changed  from 
True  to  False. 

Setting  the  iconic  resource  is  also  an  alternative  to  setting  the  initialState  resource  to 
indicate  that  a  shell  should  be  initially  displayed  as  an  icon;  the  TopLevelShell  initialize 
method  will  set  initialState  to  IconicState  if  iconic  is  True. 

See  Chapter  10,  Interdient  Communications, ,  for  more  details. 
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Name 

TransientShell  widget  class  —  pop-up  shell  that  doesn't  bypass  window  management. 

Synopsis 

Mnclude  <Xll/StringDefs .h> 
#include  <Xll/Intrinsic.h> 

widget  =  XtCreatePopupShell (name,  transientShellWidgetClass,   .  .  . ) 

Class  Hierarchy 

Core  ->  Composite  -»  Shell  ->  WMShell  ->  VendorShell  ->  TransientShell 

Description 

The  TransientShell  widget  class  is  a  subclass  of  VendorShell  that  is  used  for  pop-up  widgets 
that  don't  bypass  window-manager  interaction  (such  as  a  dialog  box  that  should  be  iconified 
when  the  application  itself  is  iconified).  For  completely  independent  pop-up  widgets,  use  an 
OverrideShell. 

Class  and  Instance  Structures 

The  TransientShellClassPart  contains  no  additional  class  fields.  Its  declaration  in 
<XlllShellP.h>  is  similar  to  those  of  the  other  shells: 

typedef   struct    { 

XtPointer   extension;         /*pointer   to   extension   record    */ 
}    TransientShellClassPart; 

The  extension  field  is  NULL. 

The  instance  structure,  TransientShellPart,  is  declared  as  follows: 

typedef   struct    { 

Widget   transient_for; 
}    TransientShellPart; 

Resources 

Transient  shells  have  the  following  resource  in  addition  to  those  inherited  from  super 
classes: 


Resource 

Class 

Representation 

Default 

Access 

XtNtransient    for 

XtCTransientFor 

XtRWidget 

NULL 

CSG 

The  realize  and  set_values  methods  of  TransientShell  store  the  WM_TRANSIENT_FOR 
property  on  the  shell  window  if  the  transient  field  in  the  WMShellPart  is  True.  If  tran- 
sient_f  or  is  non-NULL  and  the  widget  specified  by  transient_f  or  is  realized,  then  its 
window  is  used  as  the  value  of  WM_TRANSffiNT_FOR;  otherwise,  the  value  of  the  win- 
dow_group  field  in  the  WMShellPart  is  used. 
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In  addition,  TransientShell  overrides  the  value  of  the  XtNtransient  resource  from  WMShell 
(setting  it  to  True)  and  the  XtNsaveUnder  resource  from  Shell  (setting  it  to  True). 
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Name 

VendorShell  widget  class  —  vendor-specific  shell  fields  and  resources. 

Synopsis 

#include  <Xll/StringDef s .h> 
#include  <Xll/Intrinsic ,h> 

(The  VendorShell  widget  class  is  usually  not  instantiated  directly.  See  the  reference  pages  for  the 
subclasses  TransientShell,  TopLevelShell,  and  ApplicationShell  for  information  on  Shell  widget 
instantiation.) 

Class  Hierarchy 

Core  ->  Composite  -»  Shell  ->  WMShell  ->  VendorShell 

Description 

The  VendorShell  widget  class  is  a  subclass  of  WMShell  that  allows  vendors  to  provide  class 
and  instance  fields,  or  resources,  necessary  to  support  their  own  custom  window  managers.  As 
shipped  by  MIT,  the  VendorShell  widget  class  contains  no  new  class  or  instance  fields,  nor  any 
new  resources. 

Class  and  Instance  Records 

The  VendorShellClassPart  contains  no  additional  class  fields.  Its  declaration  in 
<XlllShellP.h>  is  similar  to  those  of  the  other  shells: 

typedef   struct    { 

XtPointer   extension;         /*pointer   to   extension    record    */ 
}    VendorShellClassPart; 

The  extension  field  is  NULL. 

The  instance  structure,  VendorShellPart,  is  declared  as  follows: 

typedef  struct  { 

int  vendor_specif ic; 
}  VendorShellPart; 

Resources 

As  shipped  from  MIT,  VendorShell  includes  no  new  resources. 
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Name 

WMShell  widget  class  —  application  resources  linking  window  managers. 

Synopsis 

#include  <X1 1/StringDef s . h> 
#include  <Xll/Intrinsic ,h> 

(The  WMShell  widget  class  is  usually  not  instantiated  directly.  See  the  reference  pages  for  the 
subclasses  TransientShell,  TopLevelShell,  and  ApplicationShell  for  information  on  Shell  widget 
instantiation.) 

Class  Hierarchy 

Core  ->  Composite  ->  Shell  ->  WMShell 

Description 

The  WMShell  widget  class  is  a  direct  subclass  of  Shell  that  contains  the  fields  needed  for  win 
dow-manager  interaction.  The  WMShell  class  is  not  normally  instantiated,  but  is  the  superclass 
of  all  of  the  shell  classes  that  are  instantiated,  except  for  Overrides  hell,  which  operates  without 
window  manager  intervention. 

Class  Structure 

The  WMShellClassPart  contains  no  additional  class  fields.  Its  declaration  in  the  file 
<XlllShellP.h>  is  similar  to  those  of  the  other  shells: 

typedef  struct  { 

XtPointer  extension;    /^pointer  to  extension  record*/ 
}  WMShellClassPart; 

The  extension  field  is  NULL. 

Instance  Structure 

The  instance  structure,  WMShellPart,  is  declared  as  follows: 

typedef  struct  { 
String  title; 
int  wm_timeout; 
Boolean  wait_for_wm; 
Boolean  transient; 
struct  _01dXSizeHints  { 

long  flags; 

int  x,  y; 

int  width,  height; 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 

struct  { 

int  x; 
int  y; 

}  min  aspect,  max  aspect; 
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}  size_hints; 
XWMHints  wm_hints; 

int  base_width,  base_height,  win_gravity; 
Atom  title_encoding; 
}  WMShellPart; 

The  default  values  for  the  instance  fields  in  WMShell  and  its  subclasses  are: 


Field 


title 

wm_timeout 

wait_f or_wm 

transient 

min_width 

min_height 

max_width 

max_height 

width_inc 

height_inc 

min_aspect_x 

min_aspect_y 

max_aspect_x 

max_aspect_y 

input 

initial_state 

icon_pixmap 

icon_window 

icon_x 

icon_y 

icon_mask 

window_group 

base_width 

base_height 

win_gravity 

title  encoding 


Default  Value 


Icon  name,  if  specified,  otherwise  the  application's  name 
Five  seconds 

True 

True  for  TransientShell;  False  otherwise 

XtUnspecifiedShelllnt 

XtUnspecifiedShelllnt 

XtUnspecifiedShelllnt 

XtUnspecifiedShelllnt 

XtUnspecifiedShelllnt 

XtUnspecifiedShelllnt 

XtUnspecifiedShelllnt 

XtUnspecifiedShelllnt 

XtUnspecifiedShelllnt 

XtUnspecifiedShelllnt 

False 

Normal 

None 
None 

XtUnspecifiedShelllnt 

XtUnspecifiedShelllnt 

None 

XtUnspecif iedWindow 

XtUnspecifiedShelllnt 

XtUnspecifiedShelllnt 

XtUnspecifiedShelllnt 

XA  STRING 


The  title  and  title_encoding  fields  are  stored  in  the  WM_NAME  property  on  the  shell's 
window  by  the  shell  realize  methods. 

The  wm_timeout  resource  limits  the  amount  of  time  a  shell  is  to  wait  for  confirmation  of  a 
geometry  request  to  the  window  manager.  If  none  comes  back  within  that  time,  the  shell 
assumes  the  window  manager  is  not  functioning  properly  and  sets  wait_for_wm  to  be 
False  (later  events  may  reset  this  value).  The  wait_f  or_wm  resource  sets  the  initial  state 
for  this  flag.  When  the  flag  is  False,  the  shell  does  not  wait  for  a  response  but  relies  on  asyn 
chronous  notification. 
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If  transient  is  True,  the  WM_TRANSIENT_FOR  property  will  be  stored  on  the  shell  win 
dow  with  a  value  as  specified  below.  The  interpretation  of  this  property  is  specific  to  the  win 
dow  manager  under  which  the  application  is  run. 

All  other  resources  specify  fields  in  the  window  manager  hints  and  the  window  manager  size 
hints.  The  realize  and  set_values  methods  of  WMShell  set  the  corresponding  flag  bits 
in  the  hints  if  any  of  the  fields  contain  non-default  values.  In  addition,  if  a  flag  bit  is  set  that 
refers  to  a  field  that  has  the  value  xtUnspecif  iedShelllnt,  the  value  of  the  field  is  modi 
fied  as  follows: 


Field 


base_width,  base_height 
width_inc,  height_inc 
max_width,  max_height 
min_width,  min_height 
min_aspect_x,  min_aspect_y 
max_aspect_xf  max_aspect_y 
icon_x,  icon_y 
win  gravity 


Value 


0 
1 

32767 
1 

-1 

-1 

-1 

value  returned  by  XWMGeometry  if  called; 
Otherwise  NorthWestGravity 


If  the  geometry  resource  is  non-NULL  when  a  WMShell  is  realized,  the  geometry  specification 
is  parsed  using  XWMGeometry  with  a  default  geometry  string  constructed  from  the  values  of 
x,  y,  width,  height,  width_inc  and  height_inc  and  the  size  and  position  flags  in  the 
window  manager  size  hints  are  set.  If  the  geometry  specifies  an  x  and/or  y  position,  then 
USPosition  is  set.  If  the  geometry  specifies  a  width  and/or  height  then  USSize  is  set.  Any 
fields  in  the  geometry  specification  override  the  corresponding  values  in  the  Core  x,  y,  width, 
and  height  fields.  The  geometry  string  is  not  copied  by  any  of  the  Intrinsics'  shell  classes;  a 
client  specifying  the  string  in  an  ArgList  or  varargs  list  must  ensure  that  the  value  remains 
valid  until  the  shell  widget  is  realized. 

If  the  shell  widget  is  not  the  root  of  a  widget  hierarchy,  then  the  realize  and  set_values 
methods  replace  the  value  XtUnspecif  iedwindow  in  the  window_group  field  with  the 
window  ID  of  the  root  widget  if  the  root  widget  is  realized. 

The  symbolic  constant  XtUnspecif  iedWindowGroup  may  be  used  to  indicate  that  the 
window_group  hint  flag  bit  is  not  to  be  set.  If  transient  is  True,  if  the  shell  is  not  a  sub 
class  of  TransientShell,  and  if  window_group  is  not  XtUnspecif  iedWindowGroup,  then 
the  WMShell  realize  and  set_values  methods  will  store  the  WM_TRANSIENT_FOR 
property  with  the  value  of  window_group. 

Resources 

WMShell  and  its  subclasses  have  the  following  resources  in  addition  to  those  inherited  from 
superclasses.  See  Chapter  10,  Interclient  Communications  in  Volume  Four,  X  Toolkit  Intrin 
sics  Programming  Manual  for  descriptions  of  these  resources. 
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(continued) 


WMShell 


Name 

Class 

Representation 

Default 

Access 

XtNbaseHeight 

XtCBaseHeight 

XtRInt 

See  below* 

CG 

XtNbaseWidth 

XtCBaseWidth 

XtRInt 

See  below* 

CG 

XtNheightlnc 

XtCHeightlnc 

XtRInt 

See  below* 

CG 

XtNiconMask 

XtCIconMask 

XtRBitmap 

None 

CSG 

XtNiconPixmap 

XtCIconPixmap 

XtRBitmap 

None 

CSG 

XtNiconWindow 

XtCIconWindow 

XtRWindow 

None 

CSG 

XtNiconX 

XtCIconX 

XtRInt 

See  below* 

CG 

XtNiconY 

XtCIconY 

XtRInt 

See  below* 

CG 

XtNinitialState 

XtCInitialState 

XtRInitialState 

Normal 

CG 

XtNinput 

XtCInput 

XtRBool 

False 

CG 

XtNmaxAspectX 

XtCMaxAspectX 

XtRInt 

See  below* 

CG 

XtNmaxAspectY 

XtCMaxAspectY 

XtRInt 

See  below* 

CG 

XtNmaxHeight 

XtCMaxHeight 

XtRInt 

See  below* 

CG 

XtNmaxWidth 

XtCMaxWidth 

XtRInt 

See  below* 

CG 

XtNminAspectX 

XtCMinAspectX 

XtRInt 

See  below* 

CG 

XtNminAspectY 

XtCMinAspectY 

XtRInt 

See  below* 

CG 

XtNminHeight 

XtCMinHeight 

XtRInt 

See  below* 

CG 

XtNminWidth 

XtCMinWidth 

XtRInt 

See  below* 

CG 

XtNtitle 

XtCTitle 

XtRString 

See  belowf 

CSG 

XtNtitleEncoding 

XtCTitleEncoding 

XtRAtom 

XA  STRING 

CSG 

XtNtransient 

XtCTransient 

XtRBoolean 

See  belowt 

CSG 

XtNwaitForWm 

XtCWaitForWm 

XtRBoolean 

True 

CG 

XtNwidthlnc 

XtCWidthlnc 

XtRInt 

See  below* 

CG 

XtNwinGravity 

XtCWinGravity 

XtRInt 

See  below* 

CG 

XtNwindowGroup 

XtCWindowGroup 

XtRWindow 

See  below* 

CSG 

XtNwmTimeout 

XtCWmTimeout 

XtRInt 

Five  seconds 

CG 

'Default  is  XtUnspecifiedShel lint. 

t  Default  is  Icon  name,  if  specified;  otherwise,  the  application's  name. 

^Default is  True  for TransientShell;  False  otherwise. 
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Section  4 


Intrinsics  Methods 


This  section  contains  reference  pages  for  each  Intrinsics  method.  Methods 
are  functions  that  are  written  while  implementing  a  widget  class — they  con 
tain  the  basic  code  for  the  widget.  Each  method  has  a  corresponding  pointer 
field  in  the  class  record  of  one  of  the  three  Intrinsics  classes  Core,  Compos 
ite,  or  Constraint.  The  reference  pages  in  this  section  are  named  after  these 
class  record  fields.  Since  Core  and  Constraint  have  three  field  names  in 
common,  the  Constraint  versions  have  the  word  Constraint  in  their  page 
headers.  These  Constraint  methods  are  alphabetized  together  with  the  cor 
responding  Core  methods,  not  under  the  letter  C. 

Each  page  contains  a  synopsis  of  the  function's  calling  sequence,  its  argu 
ments,  a  description  of  its  purpose  and  features,  and  a  reference  to  related 
methods  and  routines. 


In  This  Section: 


accept_focus 

change_managed 

classjnitialize 

class_part_initialize 

delete_child 

destroy 

Constraint  destroy 

display_accelerator 

expose 

geometry_manager 

get_values_hook 


initialize 

Constraint  initialize 

initialize_hook 

insert_child 

query_geometry 

realize 

resize 

set_values 

Constraint  set_values 

set_values_almost 

set  values  hook 


/  accept  focus 

— Xt  -  Intrlnsics  Methods ' 

Name 

accept_focus  —  Core  method  for  accepting  or  rejecting  the  keyboard  focus. 

Synopsis 

typedef  Boolean  ( *XtAcceptFocusProc) (Widget,  Time  *); 

Arguments 

w  Specifies  the  widget 

time  Specifies  the  X  time  of  the  event  causing  the  accept  focus. 

Description 

When  the  keyboard  focus  is  given  to  a  widget  by  its  parent,  the  parent  will  call  xtCall- 
AcceptFocus,  which  invokes  the  widget's  accept_f  ocus  method.  This  method  takes  the 
keyboard  focus  using  xtSetKeyboardFocus  and  the  Xlib  function  XSetlnputFocus 
and  must  return  a  Boolean  to  indicate  whether  the  widget  actually  took  the  focus,  so  that  the 
parent  can  give  the  focus  to  another  widget  if  necessary. 

The  accept_f  ocus  method  is  part  of  the  Core  class  structure.  A  widget  that  never  wants  the 
keyboard  focus  should  set  its  accept_f  ocus  method  to  NULL  when  it  initializes  its  class 
record. 

A  widget  can  usurp  the  keyboard  focus  by  calling  the  Xlib  function  XSetlnputFocus  expli 
citly.  Similarly,  widgets  can  be  notified  of  the  loss  of  keyboard  focus  by  specifying  translations 
or  event  handlers  for  Focus  in  and  FocusOut  events. 

See  Also 

XtCallAcceptFocus(l ),  XtSetKeyboardFocus(\ ). 
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change  managed  V 

x XI  -  Intrlnsics  Methods— 

Name 

change_managed  —  Composite  method  to  respond  to  a  change  in  a  list  of  managed  widgets. 

Synopsis 

typedef  void  (*XtWidgetProc) (Widget) ; 
Widget  w; 

Arguments 

w  Specifies  the  widget. 

Description 

The  change_managed  method  is  invoked  when  the  application  brings  the  child  under  its 
parent's  management.  This  happens  automatically  when  the  application  uses  xtCreate- 
Managedwidget  to  create  the  widget  change_managed  is  also  invoked  when  the  appli 
cation  removes  a  widget  from  the  parent's  managed  list.  Children  can  be  managed  explicitly 
with  XtManageChild,  XtManageChildren,  XtUnmanageChild,  and  XtUnmanage- 
Children. 

Since  there  are  no  additional  arguments,  the  change_managed  method  must  access  the 
widget  instance  structure  to  get  the  child  array. 

Examples 

The  change_managed  method  updates  instance  fields  that  contain  information  about  the 
managed  children,  and  then  calculates  a  new  layout.  The  following  is  the  change_managed 
method  of  the  Athena  Form  widget  class: 

static   void   ChangeManaged (w) 

Widget   w; 
{ 

FormWidget  fw  =  (FormWidget) w; 

FormConstraints  form; 

WidgetList  children,  childP; 

int  num_children  =  fw->composite .num_children; 

Widget  child; 

/* 

*  Reset  virtual  width  and  height  for  all  children. 
*/ 

for  (children  =  childP  =  fw->composite. children  ; 

childP  -  children  <  num_children;  childP++)  { 
child  =  *childP; 
if  (XtlsManaged (child) )  { 

form  =  (FormConstraints) child->core . constraints; 

/* 

*  Size  of  one  (1)  is  a  special  case  for  the  Form  widget. 
*/ 

if  (  child->core. width  !=  1) 
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(continued) 


change_managed 


form->form.virtual_width  =  (int)  child->core  .width; 
if  (  child->core.  height  !=  1) 

form->form.virtual_height  =  (int)  child->core  .height; 


Ref  igureLocations  (  (FormWidget)  w  ); 


See  Also 

Composite®),  Constraint®). 


X  Toolkit  Intrinsics  Reference  Manual 


475 


class  initialize  \ 


•Xt  -  Intrinsics  Methods — 


Name 

class_initialize  —  Core  method  for  dynamically  initializing  the  class. 

Synopsis 

typedef  void  (*XtProc); 

Description 

The  class_initialize  method  is  responsible  for  dynamically  initializing  the  class.  The 
most  common  code  in  this  method  is  for  the  registering  of  type  converters  and  the  interning  of 
atoms  and  quarks.  You  can  also  use  it  for  run-time  alterations  to  the  class  structure,  or  other 
actions  that  cannot  be  performed  at  compile  time.  The  class_initialize  method  is 
called  exactly  once  by  the  X  Toolkit. 

A  widget  class  indicates  that  it  has  no  class  initialization  procedure  by  specifying  NULL  in  the 
class_initialize  field. 

A  class  may  need  to  perform  initialization  for  fields  in  its  part  of  the  class  record.  These  are 
performed  not  just  for  the  particular  class  but  for  subclasses  as  well.  This  is  done  in  the  class's 
class_part_initialize  method,  not  in  class_initialize. 

All  widget  classes,  whether  they  have  a  class_initialize  method  or  not,  must  start  with 
their  class_inited  field  False. 

The  first  time  a  widget  of  a  class  is  created,  XtCreateWidget  ensures  that  the  widget  class 
and  all  superclasses  are  initialized,  in  superclass-to-subclass  order,  by  checking  each 
class_inited  field.  If  this  field  is  False,  XtCreateWidget  calls  the  class_ini- 
tialize  and  the  class_part_initialize  methods  for  the  class  and  all  its  superclasses. 
The  Intrinsics  then  set  the  class_inited  field  to  a  non-zero  value.  After  the  one-time  ini 
tialization,  a  class  structure  is  constant. 

The  following  provides  the  class  initialization  procedure  for  Label. 

static  void  Classlnitialize  (  ) 

{ 

XtQEleft    =  XrmStringToQuark  ("left")  ; 
XtQEcenter  =  XrmStringToQuark  ("center")  ; 
XtQEright   =  XrmStringToQuark  ("right")  ; 

XtAddConverter  (XtRString,  XtRJustify,  CvtStringToJustify,  NULL,  0); 


See  Also 

Core(3), 

class  _parl  ^initialize  (4),  initialize  (4). 
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,   ,    „  u  ,  /  class  part  initialize 

— Xt  -  Intrinslcs  Methods ' 

Name 

class_part_initialize  —  Core  method  to  initialize  class  part  structure  fields. 

Synopsis 

typedef  void  ( *XtWidgetClassProc) (WidgetClass) ; 
WidgetClass  class; 

Arguments 

class  Specifies  the  pointer  to  the  widget  class  structure. 

Description 

The  class_part_initialize  method  initializes  fields  in  a  class  part  structure.  During 
class  initialization,  the  class_part_initialize  method  for  the  class  and  for  all  its  super 
classes  is  called  in  superclass-to-subclass  order  on  the  class  record.  These  procedures  do  any 
dynamic  initializations  necessary  to  their  class's  part  of  the  record,  including  resolution  of  any 
inherited  methods  defined  in  the  class.  For  example,  if  a  widget  class  C  has  superclasses  Core, 
Composite,  A,  and  B,  then  the  class  record  for  C  is  passed  first  to  Core's  class_part_ini- 
tialize  record.  This  resolves  any  inherited  Core  methods  and  compiles  the  textual  represen 
tations  of  the  resource  list  and  action  table  that  are  defined  in  the  Core  class  part.  Next,  the 
Composite's  class_part_initialize  is  called  to  initialize  the  Composite  part  of  C's 
class  record.  Finally,  the  class_j>art_initialize  procedures  for  A,  B,  and  C  (in  order) 
are  called.  Classes  that  do  not  define  any  new  class  fields  or  that  need  no  extra  processing  for 
them  can  specify  the  class_jpart_initialize  field  to  be  NULL. 

All  widget  classes,  whether  they  have  a  class  initialization  procedure  or  not,  must  start  with 
their  class_inited  field  False. 

The  first  time  a  widget  of  a  class  is  created,  xtCreateWidget  ensures  that  the  widget  class 
and  all  superclasses  are  initialized,  in  superclass-to-subclass  order,  by  checking  each 
class_inited  field.  If  this  field  is  False,  XtCreateWidget  calls  the  class_ini- 
tialize  and  the  class_part_initialize  methods  for  the  class  and  all  its  superclasses. 
The  Intrinsics  then  set  the  class_inited  field  to  a  non-zero  value.  After  the  one-time  ini 
tialization,  a  class  structure  is  constant. 

The  following  provides  the  class_part_initialize  method  for  Form. 

static  void  ClassPartlnitialize (class) 

WidgetClass  class; 
{ 

register  FormWidgetClass  c  =  (FormWidgetClass) class; 

if  (c->form_class . layout  ==  XtlnheritLayout) 
c->form_class . layout  =  Layout; 


See  Also 

Core(3), 

class_initialize(4),  initialize^). 
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v Xt  -  Intrinsics  Methods- 
Name 

delete_child  —  Composite  method  called  when  a  child  is  destroyed. 

Synopsis 

typedef  void  (*XtWidgetProc) (Widget ); 
Widget  w; 

Arguments 

w  Specifies  the  widget 

Description 

While  removing  a  child  from  a  parent's  children  array,  xtDest  roywidget  eventually  causes 
a  call  to  the  Composite  parent's  delete_child  method. 

Most  widgets  inherit  the  delete_child  method  from  their  superclass.  Composite  widgets 
that  create  companion  widgets  define  their  own  delete_child  method  to  remove  these 
companion  widgets. 

Note  that  the  insert_child  and  delete_child  methods  exploit  internal  common  data 
structures,  so  it  would  be  unwise  to  inherit  one  and  not  the  other. 

Examples 

The  following  is  the  delete_child  method  of  the  Athena  Paned  widget  class: 

static  void  DeleteChild (w) 

Widget  w; 

{ 

/*  remove  the  subwidget  info  and  destroy  the  grip  */ 

if  (  IsPane(w)  &&  HasGrip(w)  )  XtDestroyWidget (Panelnfo (w) ->grip) ; 

/*  delete  the  child  widget  in  the  composite  children  l^st  with  the  */ 
/*  superclass  delete_child  routine.  */ 

(*SuperClass->composite_class.delete_child)  (w) ; 

}  /*  DeleteChild  */ 

See  Also 

Composite®),  Constraint®),  Core®), 
insert  child(4). 


478  X  Toolkit  Intrinsics  Reference  Manual 


— Xt  -  Intrinsics  Methods '  ' 

Name 

destroy  —  Core  method  called  when  a  widget  is  destroyed. 

Synopsis 

typedef  void  (*XtWidgetProc) (Widget) ; 
Widget  w; 

Arguments 

w  Specifies  the  widget 

Description 

The  Core  destroy  method  frees  any  memory  allocated  for  this  widget  instance. 

The  destroy  methods  are  called  in  subclass-to-superclass  order.  A  widget's  destroy 
method  should  only  deallocate  storage  originally  allocated  by  it  and  should  not  deallocate 
memory  allocated  by  its  superclasses.  If  a  widget  does  not  need  to  deallocate  any  storage,  the 
destroy  procedure  pointer  in  its  widget  class  record  can  be  NULL. 

To  reclaim  memory,  at  least  the  following  deallocations  should  be  performed: 

•  Call  XtFree  on  dynamic  storage  allocated  with  XtCalloc,  xtMalloc,  etc. 

•  Call  XFreePixmap  on  pixmaps  created  with  direct  Xlib  calls. 

•  Call  xtDestroyGC  on  GCs  allocated  with  xtGetGC. 

•  Call  XFreeGC  on  GCs  allocated  with  direct  Xlib  calls. 

•  Call  xtRemoveEventHandler  on  event  handlers  added  with  xtAddEventHandler. 

•  Call  XtRemoveTimeOut  on  timers  created  with  XtAppAddTimeOut. 

•  Call  xtDest  royWidget  for  each  child  if  the  widget  has  children  and  is  not  a  subclass  of 
compositeWidgetClass. 

Examples 

The  following  is  the  destroy  method  of  the  BitmapEdit  widget: 

static  void 
Destroy (w) 
Widget  w; 

BitmapEditWidget  cw  =  (BitmapEditWidget)  w; 

if  (cw->bitmapEdit .big_picture) 

XFreePixmap (XtDisplay (cw) ,  cw->bitmapEdit .big_picture) ; 

if  (cw->bitmapEdit .draw_gc) 

XFreeGC (XtDisplay (cw) ,  cw->bitmapEdit .draw_gc) ; 

if  (cw->bitmapEdit .undraw_gc) 

XFreeGC (XtDisplay (cw) ,  cw->bitmapEdit .undraw_gc) ; 

if  (cw->bitmapEdit .copy  gc) 
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XFreeGC(XtDisplay  (cw)  ,    cw->bitmapEdit  .  copy_gc)  ; 

/*   malloc'ed  char  array  that   stores  bitmap   state.    */ 
XtFree  (cw->bitmapEdit  .cell)  ; 


See  Also 

Composite  (3),  Constraint®),  Core(3)t 
Constraint  destroy  (4). 
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Constraint  destroy 


Name 

Constraint  destroy  —  Constraint  method  for  cleaning  up  after  a  child  is  destroyed. 

Synopsis 

typedef  void  (*XtWidgetProc) (Widget) ; 
Widget  w; 


Arguments 


Specifies  the  widget. 


Description 

The  Constraint  destroy  method  of  a  Constraint  parent  is  called  when  one  of  the  children  is 
destroyed.  This  method  cleans  up  instance  structure  fields  that  may  have  been  set  to  keep  track 
of  the  status  of  the  deleted  child. 

The  Constraint  destroy  methods  are  called  in  subclass-to-superclass  order,  starting  at  the 
widget's  parent  and  ending  at  ConstraintWidgetClass.  Therefore,  a  parent's  Constraint 
destroy  method  should  deallocate  only  storage  that  is  specific  to  the  Constraint  subclass  and 
not  the  storage  allocated  by  any  of  its  superclasses. 

If  a  parent  does  not  need  to  deallocate  any  constraint  storage,  the  Constraint  destroy  method 
entry  in  its  class  record  can  be  NULL. 

See  Also 

Composite®),  Constraint®),  Core(3). 
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display_accelerator 


•Xt  -  Intrinsics  Methods- 


Name 

display_accelerator  —  Core  method  to  display  current  accelerators. 

Synopsis 

typedef  void  (*XtStringProc) (Widget,  String) 
Widget  w; 
String  string; 

Arguments 

w  Specifies  the  source  widget  that  supplied  the  accelerators. 

string  Provides  the  string  representation  of  the  accelerators  currently  registered  for 

the  widget 

Description 

The  display_accelerator  method  of  a  widget  is  called  when  the  application  installs 
accelerators  on  that  widget  The  method  is  passed  a  string  version  of  the  current  accelerator 
table,  in  canonical  form.  This  form  may  differ  from  the  original  source  of  the  accelerator  table 
itself. 

The  Core  display_accelerator  method  is  NULL. 
See  Also 

XtlnstallAccelerators  ( 1 ) 
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/  expose 

— Xt  -  Intrinsics  Methods ' 

Name 

expose  —  Core  method  for  drawing  graphics. 

Synopsis 

typedef  void  (*XtExposeProc) (Widget,  XEvent  *,  Region); 
Widget  w; 
XEvent  *  event ; 
Region  region; 

Arguments 

w  Specifies  the  widget  instance  requiring  redisplay. 

event  Specifies  the  exposure  event  giving  the  rectangle  requiring  redisplay. 

region  Specifies  the  union  of  all  rectangles  in  this  exposure  sequence. 

Description 

The  expose  method  is  responsible  for  initially  drawing  into  a  widget's  window  and  for 
redrawing  the  window  every  time  a  part  of  the  window  becomes  exposed.  This  redrawing  is 
necessary  because  the  X  server  does  not  normally  maintain  the  contents  of  windows  when  they 
are  obscured.  When  a  window  becomes  visible  again,  it  must  be  redrawn. 

The  expose  method  usually  needs  to  modify  its  drawing  based  on  the  geometry  of  the  window 
and  other  instance  variables  set  in  other  methods.  For  example,  the  Label  widget  will  left- 
justify,  center,  or  right-justify  its  text  according  to  the  xtN justify  resource,  and  the  actual 
position  to  draw  the  text  depends  on  the  widget's  current  size. 

Another  factor  to  consider  when  writing  the  expose  method  is  that  many  widgets  also  draw 
from  action  routines,  in  response  to  user  events.  For  example,  BitmapEdit  (described  in  Vol 
ume  Four,  X  Toolkit  Intrinsics  Programming  Manual)  toggles  bitmap  cells  in  action  routines. 
The  expose  method  must  be  capable  of  redrawing  the  current  state  of  the  widget  at  any  time. 
This  means  that  action  routines  usually  set  instance  variables  when  they  draw  so  that  the 
expose  method  can  read  these  instance  variables  and  draw  the  right  thing.  Usually,  actions 
that  draw  either  share  drawing  code  with  the  expose  method  or  invoke  the  expose  method 
directly. 

Most  widgets  keep  track  of  what  they  draw  in  some  form  of  arrays  or  display  lists.  When  they 
need  to  redraw,  they  simply  replay  the  saved  drawing  commands  in  the  original  order  to  redraw 
the  window.  For  example,  BitmapEdit  keeps  track  of  the  state  of  each  bitmap  cell  in  a  charac 
ter  array.  It  could  easily  traverse  this  array  and  redraw  each  cell  that  is  set  in  the  array. 

However,  BitmapEdit  does  not  use  this  strategy.  To  improve  its  scrolling  performance,  the 
expose  method  copies  an  off-screen  pixmap  into  the  window  whenever  redisplay  is  required. 
The  actions  draw  into  this  off-screen  pixmap  and  then  call  the  expose  method  directly  to  have 
the  pixmap  copied  to  the  window.  This  strategy  is  fast,  but  it  uses  up  a  relatively  large  amount 
of  server  memory. 

The  expose  method  is  passed  an  event  that  contains  the  bounding  box  of  the  area  exposed. 
You  should  copy  only  this  area  from  the  pixmap  to  the  window.  The  BitmapEdit  widget  takes 
advantage  of  this,  too.  It  manufactures  an  artificial  event  containing  the  bounding  box  of  the 
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cell  to  be  toggled,  and  it  passes  this  event  when  it  calls  expose.  This  causes  the  expose 
method  to  copy  only  the  one  just-updated  cell  to  the  window. 

The  example  below  shows  the  expose  method  from  the  BitmapEdit  widget. 

/*  ARGSUSED  */ 
static  void 
Redisplay (cw,  event) 
BitmapEditWidget  cw; 
XExposeEvent  *event; 
{ 

register  int  x,  y; 

unsigned  int  width,  height; 

if  ( IXtlsRealized(cw) ) 
return; 

if  (event)  {   /*  called  from  btn-event  */ 

x  =  event->x; 

y  =  event->y; 

width  =  event->width; 

height  =   event->height; 
} 
else  {        /*  called  because  of  expose  */ 

x  =  0; 

y  =  0; 

width  =  cw->bitmapEdit .pixmap_width_in_pixels; 

height  =  cw->bitmapEdit .pixmap_height_in_pixels; 
} 

if  (Def aultDepthOf Screen (XtScreen (cw) )  ==  1) 

XCopyArea (XtDisplay (cw) ,  cw->bitmapEdit .big_picture, 
XtWindow (cw) , 

cw->bitmapEdit  .copy_gc,  x  +  cw->bitmapEdit .  cur^x,  y  + 
cw->bitmapEdit .cur_y,  width,  height,  x,  y) ; 

else 

XCopyPlane (XtDisplay (cw) ,  cw->bitmapEdit .big_picture, 
XtWindow (cw) , 

cw->bitmapEdit .copy_gc,  x  +  cw->bitmapEdit . cur_x,  y  + 
cw->bitmapEdit .cur_y,  width,  height,  x,  y,  1); 


Note  that  the  expose  method  first  checks  to  see  that  the  widget  is  realized  using  xt- 
isRealized.  This  is  a  precaution  against  the  unlikely  event  that  an  instance  of  this  widget  is 
suddenly  destroyed  or  unrealized  by  an  application  while  Expose  events  are  still  pending.  If 
this  did  happen,  drawing  on  the  nonexistent  window  would  cause  an  X  protocol  error. 

Next,  BitmapEdit's  expose  method  sets  the  rectangle  it  will  redraw  based  on  the  event  passed 
in  by  Xt. 

If  the  compress_exposure  field  of  the  class  structure  is  initialized  to  xtExpose- 
CompressMultiple,  as  it  is  in  BitmapEdit,  then  Xt  automatically  merges  the  multiple 
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contiguous  Expose  events  that  may  occur  because  of  one  or  more  user  actions  into  one 
Expose  event.  In  this  case,  the  Expose  event  contains  the  bounding  box  of  the  areas  expo 
sed.  BitmapEdit  redraws  everything  in  this  bounding  box. 

If  the  widget's  compress_exposure  class  field  specifies  XtExposeNoCompress,  or  if 
the  event  type  is  NoExpose,  then  region  is  NULL;  otherwise,  the  event  is  the  final  event  in 
the  compressed  series,  but  x,  y,  width  and  height  then  contain  the  bounding  box  for 
region.  There  are  numerous  flags  for  the  compress_exposure  field.  For  more  informa 
tion,  see  Chapter  5,  Inside  a  Widget,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Man 
ual. 

For  widgets  that  are  very  time-consuming  for  the  client  or  server  to  redraw,  you  might  want  to 
use  the  third  argument  of  the  expose  method,  which  is  a  region.  The  Region  type  is 
opaquely  defined  by  Xlib  (internally  a  linked  list  of  rectangles).  The  Region  passed  into 
expose  describes  the  union  of  all  the  areas  exposed  by  a  user  action.  You  can  use  this  region 
to  clip  output  to  the  exposed  region  (using  XSetRegion  to  set  the  GC),  and  possibly  calculate 
which  drawing  primitives  affect  this  area.  Xlib  provides  region  mathematics  routines  (such  as 
XRectlnRegion)  to  compare  the  regions  in  which  your  widget  needs  to  draw  with  the  region 
needing  redrawing.  If  certain  areas  do  not  require  redrawing,  you  can  skip  the  code  that 
redraws  them,  thereby  saving  valuable  time.  However,  if  this  calculation  is  complicated,  its 
cost/benefit  ratio  should  be  examined. 

Each  of  these  exposure  handling  techniques  may  be  the  best  for  certain  widgets.  For  a  com 
plete  description  of  Expose  event  handling  strategies,  see  Chapter  8,  Events,  in  Volume  One, 
Xlib  Programming  Manual. 

The  remainder  of  BitmapEdit's  expose  method  shown  in  the  example  above  consists  of  a 
single  Xlib  call  to  copy  from  the  backup  pixmap  into  the  widget's  window.  Note  that  one  of 
two  Xlib  routines  is  called  based  on  the  depth  of  the  screen.  This  is  because  XCopyArea  is 
slightly  more  efficient  than  XCopy Plane  and  should  be  used  when  drawing  on  a  monochrome 
screen. 

Note  that  instance  variables  are  used  for  the  arguments  of  the  Xlib  routines  in  the  example 
above.  See  the  reference  page  for  each  routine  in  Volume  Two,  Xlib  Reference  Manual,  when 
you  need  to  call  them  in  your  code. 

See  Chapters  5,  6,  and  7  in  Volume  One,  Xlib  Programming  Manual,  for  more  information  on 
the  GC,  drawing  graphics,  and  color,  respectively. 

If  a  widget  has  no  display  semantics,  it  can  specify  NULL  for  the  expose  field.  Many  compos 
ite  widgets  serve  only  as  containers  for  their  children  and  have  no  expose  method.  If  the 
expose  method  is  NULL,  XtRealizeWidget  fills  in  a  default  bit  gravity  of  Northwest- 
Gravity  before  it  calls  the  widget's  realize  method. 

Sometimes  it  is  possible  to  anticipate  the  display  needs  of  several  levels  of  subclasses.  For 
example,  rather  than  maintaining  separate  expose  methods  for  the  widgets  Command,  Label, 
and  Toggle,  they  share  a  single  redisplay  routine.  Doing  this,  however,  requires  the  top  super 
class  to  foresee  the  needs  of  all  the  subclasses.  The  Label  widget's  expose  method  has 
parameters  that  it  doesn't  use,  but  that  Command  and  Toggle  use  when  they  inherit  the 
expose  method  from  Label. 
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Some  widgets  use  substantial  computing  resources  to  display  data.  However,  this  effort  is 
wasted  if  the  widget  is  not  actually  visible  on  the  screen  (e.g.,  when  the  widget  is  obscured  by 
another  application  or  is  iconified).  The  visible  field  in  the  Core  widget  instance  structure 
provides  the  widget  with  a  hint  that  it  need  not  display  data.  If  the  widget  is  visible,  the  visi 
ble  field  is  guaranteed  to  be  True  by  the  time  an  Expose  event  is  processed;  if  the  widget  is 
not  visible,  this  field  is  usually  False. 

Widgets  can  either  use  or  ignore  the  visible  hint.  If  they  ignore  it,  the  visible_inter- 
est  field  in  their  widget  class  record  should  be  set  to  False.  In  such  cases,  the  visible 
field  is  initialized  to  True  and  never  changes,  but  if  visible_interest  is  True,  the  event 
manager  asks  for  visibilityNotif y  events  for  the  widget  and  updates  the  visible  field 
accordingly. 

Structures 

The  definition  of  a  Region  is  given  in  <XlllXutil.h>.  Region  is  an  opaque  type  defined  by 
Xlib.  A  Region  is  a  linked  list  of  rectangles. 

See  Also 

Core(3) 
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Name 

geometry_manager  —  Composite  method  called  when  a  child  requests  a  new  geometry. 


Synopsis 

typedef  XtGeometryResult  (*XtGeometryHandler) (Widget,  XtWidgetGeometry  *); 
Widget  w, 

XtWidgetGeometry  *reguest; 
XtWidgetGeometry  *geometry_return; 

Arguments 

w  Specifies  the  widget 

request  Specifies  the  requested  geometry. 

geometry _return 

Specifies  the  reply  geometry. 

Description 

The  geometry_manager  method's  job  is  to  respond  to  a  proposal  from  a  child  for  a  new 
size  of  that  child. 

A  class  can  inherit  its  superclass's  geometry  manager  during  class  initialization,  by  using  the 
XtlnheritGeometryManager  symbol  in  the  class  structure  initialization.  However,  there 
is  no  default  geometry  manager  defined  by  Composite.  Therefore,  direct  subclasses  of  Compo 
site  or  Constraint  either  define  a  geomet  ry_manager  or  set  it  to  NULL. 

A  bit  set  to  zero  in  the  request's  mask  field  means  that  the  child  widget  does  not  care  about  the 
value  of  the  corresponding  field.  Then,  the  geometry  manager  can  change  it  as  it  wishes.  A  bit 
set  to  1  means  that  the  child  wants  that  geometry  element  changed  to  the  value  in  the  corre 
sponding  field. 

If  the  geometry  manager  can  satisfy  all  changes  requested,  and  if  xtCWQueryOnly  is  not 
specified,  it  updates  the  widget's  x,  y,  width,  height,  and  border_width  values  appro 
priately.  Then,  it  returns  XtGeometryYes,  and  the  value  of  the  geomet ry_return  argu 
ment  is  undefined.  The  widget's  window  is  moved  and  resized  automatically  by  xtMake- 
GeometryRequest. 

Homogeneous  Composite  widgets  often  find  it  convenient  to  treat  the  widget  making  the 
request  the  same  as  any  other  widget,  possibly  reconfiguring  it  as  part  of  its  layout  process, 
unless  XtCWQueryOnly  is  specified.  If  it  does  this,  it  should  return  Xt  Geomet  ryDone  to 
inform  XtMakeGeometryRequest  that  it  does  not  need  to  do  the  configuration  itself. 

Although  XtMakeGeometryRequest  resizes  the  widget's  window  (if  the  geometry  man 
ager  returns  XtGeometryYes),  it  does  not  call  the  widget  class's  resize  procedure.  The 
requesting  widget  must  perform  whatever  resizing  calculations  are  needed  explicitly. 

If  the  geometry  manager  chooses  to  disallow  the  request,  the  widget  cannot  change  its  geome 
try.  The  value  of  the  geomet ry_ret urn  argument  is  undefined,  and  the  geometry  manager 
returns  Xt  Geomet  ryNo. 
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Sometimes  the  geometry  manager  cannot  satisfy  the  request  exactly,  but  it  may  be  able  to  sat 
isfy  a  similar  request  That  is,  it  could  satisfy  only  a  subset  of  the  requests  (for  example,  size 
but  not  position)  or  a  lesser  request  (for  example,  it  cannot  make  the  child  as  big  as  the  request 
but  it  can  make  the  child  bigger  than  its  current  size).  In  such  cases,  the  geometry  manager  fills 
in  geometry_return  with  the  actual  changes  it  is  willing  to  make,  including  an  appropriate 
mask,  and  returns  XtGeometryAlmost. 

If  a  bit  in  geometry_return->request_mode  is  0,  the  geometry  manager  does  not 
change  the  corresponding  value  if  the  geometry_return  argument  is  used  immediately  in  a 
new  request  If  a  bit  is  1 ,  the  geometry  manager  does  change  that  element  to  the  corresponding 
value  in  eometry_return.  More  bits  may  be  set  in  geometry_return  than  in  the  original 
request  if  the  geometry  manager  intends  to  change  other  fields  should  the  child  accept  the  com 
promise. 

When  XtGeometryAlmost  is  returned,  the  widget  must  decide  if  the  compromise  suggested 
in  geometry_return  is  acceptable.  If  it  is,  the  widget  must  not  change  its  geometry 
directly;  rather,  it  must  make  another  call  to  XtMakeGeometryRequest. 

If  the  next  geometry  request  from  this  child  uses  the  geometry_return  box  filled  in  by  an 
XtGeometryAlmost  return,  and  if  there  have  been  no  intervening  geometry  requests  on 
either  its  parent  or  any  of  its  other  children,  the  geometry  manager  must  grant  the  request,  if 
possible.  That  is,  if  the  child  asks  immediately  with  the  returned  geometry,  it  should  get  an 
answer  of  xtGeometryYes.  However,  the  user's  window  manager  may  affect  the  final  out 
come. 

To  return  an  XtGeometryYes,  the  geometry  manager  frequently  rearranges  the  position  of 
other  managed  children  by  calling  xtMoveWidget.  However,  a  few  geometry  managers  may 
sometimes  change  the  size  of  other  managed  children  by  calling  xtResizeWidget  or  xt- 
Conf  igurewidget.  If  XtCWQueryOnly  is  specified,  the  geometry  manager  must  return 
how  it  would  react  to  this  geometry  request  without  actually  moving  or  resizing  any  widgets. 

Geometry  managers  must  not  assume  that  the  request  and  geometry_return  arguments 
point  to  independent  storage.  The  caller  is  permitted  to  use  the  same  field  for  both,  and  the 
geometry  manager  must  allocate  its  own  temporary  storage,  if  necessary. 

Structures 

The  Xtwidget Geometry  structure  is  similar,  but  not  identical,  to  the  corresponding  Xlib 
structure: 

typedef   unsigned   long   XtGeometryMask; 

typedef   struct    { 

XtGeometryMask   request_mode; 

Position    x,    y; 

Dimension  width,  height; 

Dimension  border_width; 

Widget  sibling; 

int  stack_mode; 
}  XtWidgetGeometry; 
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The  request_mode  definitions  are  from  <Xll/X.h>: 


#define 

CWX 

(1«0) 

tdefine 

CWY 

(1«1) 

#define 

CWWidth 

(1«2) 

#define 

CWHeight 

d«3) 

tdefine 

CWBorderWidth 

d«4) 

tdef  ine 

CWSibling 

(1«5) 

#def  ine 

CWStackMode 

d«6) 

The  Xt  Intrinsics  also  support  the  following  value: 

#define  XtCWQueryOnly         (1«7) 

XtCWQueryOnly  indicates  that  the  corresponding  geometry  request  is  only  a  query  as  to  what 
would  happen  if  this  geometry  request  were  made  and  that  no  widgets  should  actually  be 
changed. 

XtMakeGeometryRequest,  like  the  Xlib  XConf  igureWindow  function,  uses 
request_mode  to  determine  which  fields  in  the  Xt  Widget  Geometry  structure  you  want 
to  specify. 

The  stack_mode  definitions  are  from  <Xll/X.h>: 

#define  Above  0 

#define  Below  1 

tdefine  Toplf  2 

#define  Bottomlf  3 

tdefine  Opposite  4 

The  Intrinsics  also  support  the  following  value: 

#define         XtSMDontChange      5 

For  precise  definitions  of  Above,  Below,  Toplf,  Bottomlf,  and  Opposite,  see  the  refer 
ence  page  for  Conf igureWindow  in  Volume  Two,  Xlib  Reference  Manual.  XtSMDont 
Change  indicates  that  the  widget  wants  its  current  stacking  order  preserved. 

Examples 

The  following  is  the  geometry_manager  method  of  the  Athena  Form  widget  class: 

/*  ARGSUSED  */ 

static  XtGeometryResult  GeometryManager (w,  request,  reply) 

Widget  w; 

XtWidgetGeometry  *request; 

XtWidgetGeometry  *reply;     /*  RETURN  */ 
{ 

FormConstraints  form  =  (FormConstraints) w->core . constraints; 

XtWidgetGeometry  allowed; 

if  ( (request->request_mode  &  "(XtCWQueryOnly  I  CWWidth  I  CWHeight))  II 

! f orm->f orm. allow_resize) 
return  XtGeometryNo; 
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if  (request->request_mode  &  CWWidth) 

allowed.  width  =  request->width; 
else 

allowed.  width  =  w->core  .width; 

if  (request->request_mode  &  CWHeight) 
allowed.  height  =  request->height; 
else 

allowed.  height  =  w->core  .height  / 

if  (allowed.  width  ==  w->core  .width  && 

allowed.  height  ==  w->core  .height  ) 
return  XtGeometryNo; 

if  (  !  (request->request_mode  &  XtCWQueryOnly)  )  { 

/*  reset  virtual  width  and  height.  */ 

form->form.virtual_width  =  w->core  .width  =  allowed  .  width; 

form->form.virtual_height  =  w->core  .height  =  allowed.  height; 

Ref  igureLocations  (  (FormWidget)  w->core  .parent  ); 
} 
return  XtGeometryYes; 


See  Also 

Composite®),  Constraint®),  Core(3), 
Constraint  destroy  (4). 
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J  get_values_hook 


Name 

get_values_hook  —  Core  method  for  getting  subpart  resource  values. 

Synopsis 

typedef  void  ( *XtArgsProc) (Widget,  ArgList,  Cardinal  *); 
Widget  w; 
ArgList  args; 
Cardinal  *num_args; 

Arguments 

w  Specifies  the  widget  whose  subpart  resource  values  are  to  be  retrieved. 

args  Specifies  the  argument  list  that  was  passed  to  xtSetValues. 

n  um_args  Specifies  the  number  of  arguments  in  the  argument  list. 

Description 

Widgets  can  return  resource  values  from  subparts  when  the  application  calls  xtGetValues 
by  supplying  a  get_values_hook  method. 

The  get_values_hook  method  should  call  xtGetSubvalues  and  pass  the  appropriate 
resource  list. 

The  hook  methods  are  called  with  different  arguments  than  their  nonhook  counterparts.  They 
are  passed  a  single  copy  of  the  widget  instance  structure  (the  new  copy  already  modified  in  the 
nonhook  methods),  and  the  argument  list  passed  to  the  Xt  routine  that  triggered  the  method. 
The  set_values_hook  and  get_values_hook  methods  simply  take  this  widget  ID  and 
argument  list  and  pass  them  to  xtSetSubvalues  or  XtGetSubvalues,  respectively. 

The  get_values_hoolc  methods  are  called  in  superclass-to-subclass  order  after  all  the 
resource  values  have  been  fetched  by  XtGetValues. 

As  of  Release  4,  the  initialize_hook  and  set_values_hook  methods  are  still  called 
for  backwards  compatibility  but  are  obsolete  because  the  same  information  (the  argument  lists) 
has  been  added  as  arguments  to  the  initialize  and  set_values  methods.  However, 
get_values_hook  is  still  necessary. 

Examples 

The  example  below  shows  the  get_values_hook  method  for  the  AsciiSrc  subpart  of  the  R3 
Text  widget  (somewhat  simplified  to  show  only  the  essential  elements). 

static  void 

GetValuesHook (src,  args,  num_args) 

XawText Source  src; 

ArgList  args; 

Cardinal  *  num_args; 
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XtGetSubvalues  (  (caddr_t)  src, 

sour  ceRe  sources, 

XtNumber  (sourceResources)  , 

args, 

*num_args)  ; 


See  Also 

XtCreateWidget(l\  XtGetSubvalues  (I),  XtGetValues(\\ 
Core(3). 
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Name 

initialize  —  Core  method  for  initializing  instance  variables. 

Synopsis 

typedef  void  (*XtInitProc) (Widget) ; 
Widget  request,  new; 

Arguments 

request  Specifies  the  widget  with  resource  values  as  requested  by  the  argument  list, 

the  resource  database,  and  the  widget  defaults. 

new  Specifies  a  widget  with  the  new  values,  both  resource  and  nonresource,  as 

modified  by  the  initialize  method. 

Description 

The  initialize  method  performs  the  following: 

•  Allocates  space  for  and  copies  any  resources  that  are  referenced  by  address.    For 
example,  if  a  widget  has  a  field  that  is  a  String,  it  cannot  depend  on  the  characters  at 
that  address  remaining  constant  but  must  dynamically  allocate  space  for  the  string  and 
copy  it  to  the  new  space.  (Note  that  you  should  neither  allocate  space  for  nor  copy  call 
back  lists.) 

•  Computes  values  for  unspecified  resource  fields.  For  example,  if  width  and  height 
are  zero,  the  widget  should  compute  an  appropriate  width  and  height  based  on  other 
resources.  This  is  the  only  time  that  a  widget  should  ever  directly  assign  its  own  width 
and  height  Note  that  a  widget  may  only  directly  assign  its  own  width  and  height  within 
the  initialize,  set_va lues,  and  set_values_hook  methods. 

•  Computes  values  for  uninitialized  nonresource  fields  that  are  derived  from  resource 
fields.   For  example,  graphics  contexts  (GCs)  that  the  widget  uses  are  derived  from 
resources  such  as  background,  foreground,  and  font. 

•  Supersedes  values  in  the  superclass,    initialize  methods  are  called  in  super- 
class-to-subclass  order.  The  main  purpose  of  a  subclass  may  be  to  change  nonresource 
data  in  a  superclass,  since  the  subclass  has  direct  access  to  the  instance  record.  In  partic 
ular,  size  calculations  of  a  superclass  are  often  incorrect  for  a  subclass,  and  the  subclass 
must  modify  or  recalculate  fields  declared  and  computed  by  its  superclass. 

•  Checks  certain  fields  for  internal  consistency.  For  example,  it  makes  no  sense  to  specify 
a  colormap  and  a  visual  together  when  the  colormap  was  not  created  with  the  given 
visual. 

initialize  methods  are  called  in  superclass-to-subclass  order  after  all  fields  specified  in  the 
resource  lists  have  been  initialized.  The  initialize  method  does  not  need  to  examine  the 
arguments  if  all  public  resources  are  declared  in  the  resource  list.  Most  of  the  initialization 
code  for  a  specific  widget  class  deals  with  fields  defined  in  that  class,  not  with  fields  defined  in 
its  superclasses. 
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If  a  subclass  does  not  need  an  initialize  method  because  it  does  not  need  to  perform  any 
of  the  above  operations,  it  can  specify  NULL  for  the  initialize  field  in  the  class  record. 

Sometimes  a  subclass  may  want  to  overwrite  values  filled  in  by  its  superclass.  In  particular, 
size  calculations  of  a  superclass  are  often  incorrect  for  a  subclass  and  in  this  case,  the  subclass 
must  modify  or  recalculate  fields  declared  and  computed  by  its  superclass. 

As  an  example,  a  subclass  can  visually  surround  its  superclass  display.  In  this  case,  the  width 
and  height  calculated  by  the  superclass's  initialize  method  are  too  small  and  need  to  be 
incremented  by  the  size  of  the  surround.  The  subclass  needs  to  know  whether  its  superclass's 
size  was  calculated  by  the  superclass  or  specified  explicitly.  All  widgets  must  place  themselves 
into  whatever  size  is  explicitly  given,  but  they  should  compute  a  reasonable  size  if  no  size  is 
requested. 

The  request  and  new  arguments  provide  the  necessary  information  for  a  subclass  to  deter 
mine  the  difference  between  a  specified  size  and  a  size  computed  by  a  superclass.  The 
request  widget  is  the  widget  as  originally  requested.  The  new  widget  starts  with  the  values 
in  the  request,  but  it  has  been  updated  by  all  the  superclass's  initialize  methods  called  so 
far.  A  subclass's  initialize  method  can  compare  these  two  to  resolve  any  potential  con 
flicts. 

In  the  above  example,  the  subclass  with  the  visual  surround  can  see  if  the  width  and  height  in 
the  request  widget  are  zero.  If  so,  it  adds  its  surround  size  to  the  width  and  height  fields 
in  the  new  widget.  If  not,  it  must  make  do  with  the  size  originally  specified. 

The  new  widget  becomes  the  actual  widget  instance  record.  Therefore,  the  initialize 
method  should  change  only  the  new  widget  (the  request  widget  is  for  reading  only),  and  if 
the  method  needs  to  call  any  routines  that  operate  on  a  widget,  it  should  specify  new  as  the 
widget  instance. 

At  a  minimum,  the  initialize  method  must  compute  values  for  Core,width  and  height,  if 
they  have  not  been  computed  by  a  superclass.  This  is  the  only  time  that  a  widget  should  ever 
directly  assign  its  own  width  and  height. 

Examples 

Here  is  the  initialize  method  from  Label: 

/*  ARGSUSED  */ 

static  void  Initialize (request,  new) 

Widget  request,  new; 

{ 

LabelWidget  Iw  =  (LabelWidget)  new; 

if  (lw->label. label  ==  NULL) 

lw->label . label  =  XtNewString (lw->core. name) ; 
else  { 

lw->label. label  =  XtNewString (lw->label . label) ; 
} 

GetnormalGC (Iw) ; 
GetgrayGC (Iw) ; 

SetTextWidthAndHeight (Iw) ; 
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if  (lw->core. width  ==  0) 

lw->core. width  =  lw->label . label_width  +  2  *  lw->label . internal_width; 
if  (lw->core. height  ==  0) 

lw->core. height  =  lw->label . label_height  +  2*lw->label . internal  height; 

lw->label .label_x  =  lw->label . label_y  =  0; 
(*XtClass (new) ->core_class. resize)  ( (Widget) Iw) ; 


See  Also 

CoreQ), 
initialize  hook(4). 
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Name 

Constraint  initialize 


Constraint  method  to  initialize  constraint  resources. 


Synopsis 

typedef  void  (  *XtInitProc)  (request,  new); 
Widget  request,  new; 


Arguments 

request 


Specifies  the  widget  with  resource  values  as  requested  by  the  argument  list, 
the  resource  database,  and  the  widget  defaults. 

new  Specifies  a  widget  with  the  new  values,  both  resource  and  nonresource,  as 

modified  by  the  initialize  procedure. 

Description 

The  Constraint  initialize  method  of  a  Constraint  parent  is  called  just  after  the  Core  ini 
tialize  method  of  a  child  is  called  during  child  creation.  The  Constraint  initialize 
method  should  compute  any  constraint  fields  derived  from  constraint  resources.  It  can  make 
changes  to  the  child  widget  to  make  it  conform  to  the  specified  constraints;  for  example,  chang 
ing  the  child's  size  or  position. 

The  values  passed  to  the  parent  Constraint  initialize  method  are  the  same  as  those  passed 
to  the  child's  initialize  method. 

If  a  Constraint  class  does  not  need  a  Constraint  initialize  method,  it  can  specify  NULL  for 
the  initialize  field  of  the  Const  raintClassPart  in  the  class  record. 

Examples 

The  following  is  the  Constraint  initialize  method  of  the  Athena  Form  widget  class: 

/*  ARGSUSED  */ 

static  void  Constraintlnitialize  (request,  new) 

Widget  request,  new; 
{ 

FormConstraints  form  =  (FormConstraints)  new->core  .constraints; 

FormWidget  fw  =  (FormWidget  )  new->core  .parent  ; 

f  orm->form.  virtual_width  =  (int)  new->core.  width; 
form->form.  virtual_height  =  (int)  new->core  .height; 

if  (form->form.dx  ==  default_value) 

form->form.dx  =  f  w->form.def  ault_spacing; 

if  (form->f  orm.  dy  ==  def  ault_value) 

form->f  orm.dy  =  fw->form.default_spacing; 


See  Also 

Composite®),  Constraint®),  Core(3), 
Constraint  destroy  (4),  Constraint  set_values(4). 
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Name 

initializejiook  —  Core  method  for  initializing  subpart  data. 

Synopsis 

typedef  void  (*XtArgsProc) (Widget,  ArgList,  Cardinal  *); 
Widget  w; 
ArgList  args; 
Cardinal  *num_args; 

Arguments 

w  Specifies  the  widget  whose  subpart  data  is  to  be  retrieved. 

args  Specifies  the  argument  list  that  was  passed  to  xtCreateWidget. 

num_args  Specifies  the  number  of  arguments  in  the  argument  list. 

Description 

The  initialize_hook  method  allows  a  widget  instance  to  initialize  subpart  data  using 
information  from  the  specified  argument  list.  For  example,  the  R3  Text  widget  had  subparts 
that  were  not  widgets,  yet  these  subparts  had  resources  that  could  be  specified  by  means  of  the 
resource  file  or  an  argument  list.  (The  R4  Text  widget  uses  objects  to  achieve  the  same  modu 
larity.) 

If  initialize_hook  is  not  NULL,  then  it  is  called  immediately  after  the  corresponding 
initialize  method  or  in  its  place  if  the  initialize  method  is  NULL. 

The  hook  methods  are  called  with  different  arguments  than  their  nonhook  counterparts.  They 
are  passed  a  single  copy  of  the  widget  instance  structure  (the  new  copy  already  modified  in  the 
nonhook  methods),  and  the  argument  list  passed  to  the  Xt  routine  that  triggered  the  method. 
The  initialize_hook  method  uses  the  contents  of  the  argument  list  to  validate  resource 
settings  for  subparts  and  set  nonresource  subpart  data. 

As  of  Release  4,  the  initialize_hook  and  set_values_hook  methods  are  still  called 
for  backwards  compatibility  but  are  obsolete  because  the  same  information  (the  argument  lists) 
has  been  added  as  arguments  to  the  initialize  and  set_values  methods.  (However,  the 
get_values_hook  method  is  still  necessary.) 

Examples 

The  following  is  the  initialize_hook  method  of  the  Athena  AsciiText  widget  class.  This 
particular  method  creates  the  source  and  sink  objects,  which  are  replaceable  parts  of  the  Text 
widget. 

static  void 

CreateSourceSink (widget,  args,  num_args) 

Widget  widget; 

ArgList  args; 

Cardinal  *num_args; 

AsciiWidget  w  =  (AsciiWidget)  widget; 
int  i; 
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int  tabs[TAB_COUNT]  ,  tab; 

w->text  .source  =  XtCreateWidget  (  "textSource",  asciiSrcOb  jectClass, 

widget,  args,  *num_args  ); 

w->text.sink  =  XtCreateWidget  (  "textSink",  asciiSinkOb  jectClass, 
widget,  args,  *num_args  ); 

if  (w->core.  height  ==  DEFAULT_TEXT_HEIGHT) 

w->core.  height  =  VMargins  (w)  +  XawTextSinkMaxHeight  (w->text  .  sink,  1); 

for  (i=0,  tab=0  ;  i  <  TAB_COUNT  ;  i++) 
tabs[i]  -  (tab  +=  8)  ; 

XawTextSinkSetTabs  (w->text  .  sink,  TAB_COUNT,  tabs); 

XawTextDisableRedisplay  (widget)  ; 
XawTextEnableRedisplay  (widget)  ; 


See  Also 

XtCreateWidget(l\  XtGetSubvalues(l), 

Core(3), 

get_values_hook(4),  set_values_hook(4),  initialize^). 
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—  Xt  -  Intrinsics  Methods ' 

Name 

insert_child  —  Composite  method  to  insert  a  child  into  the  array  of  children. 

Synopsis 

typedef  void  (*XtWidgetProc) (Widget) ; 
Widget  w; 

Arguments 

w  Specifies  the  widget. 

Description 

To  add  a  child  to  the  parent's  list  of  children,  xtCreateWidget  calls  the  parent's 
insert_child  method. 

Most  composite  widgets  inherit  this  method  from  their  superclass  by  specifying  Xt  Inherit - 
insertChild  for  the  insert_child  field  in  the  class  record.  Composite's 
insert_child  method  calls  the  insert_position  function  (set  with  the  XtNinsert- 
Position  resource)  and  inserts  the  child  at  the  specified  position. 

Some  Composite  widgets  define  their  own  insert_child  method  so  that  they  can  order 
their  children  in  some  convenient  way,  create  companion  controller  widgets  for  a  new  widget, 
or  limit  the  number  or  class  of  their  children  widgets. 

A  Composite  widget  class  that  wishes  to  allow  non- widget  children  (i.e.,  Objects  or  Rect- 
Objs)  must  initialize  a  CompositeClassExtension  extension  record  and  set  the 
accepts_objects  field  in  this  record  to  True.  If  the  CompositeClassExtension 
record  is  not  specified  or  the  accepts_ob  jects  field  is  False,  the  Composite  widget  can 
assume  that  all  its  children  are  widgets  without  an  explicit  subclass  test  in  the 
insert_child  method. 

This  method  can  also  be  inherited  dynamically  and  modified  if  the  subclass  widget  wants  to  use 
it  but  wants  to  perform  additional  processing  when  the  child  is  inserted.  The  example 
InsertChild  method  shown  below  does  this: 

static  XtArgsProc  InsertChild (w,  args,  num_args) 

Widget  w; 

ArgList  args; 

Cardinal  *num_args; 

{ 

Compos iteWidget Class  superclass; 

/* 

*  Satisfy  parental  responsibilities 

*/ 

superclass  =  (CompositeWidgetClass)  compositeWidgetClass; 
(*superclass->composite  class. insert  child) (wf args, num  args); 
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If  there  is  not  enough  room  to  insert  a  new  child  in  the  children  array  (that  is,  num_children 
=  num_slots),  the  insert_child  method  must  first  reallocate  the  array  and  update 
num_slots.  The  insert_child  method  then  places  the  child  wherever  it  wants  and  incre 
ments  the  num_children  field. 

Examples 

The  following  is  the  insert_child  method  of  the  Athena  Paned  widget  class: 

static   void    InsertChild (w,    args,    argcount) 

register   Widget   w; 

ArgList    args; 

Cardinal    *argcount; 

{ 

Pane  pane  =  Panelnfo (w) ; 

/*  insert  the  child  widget  in  the  composite  children  list  with  the  */ 
/*  superclass  insert_child  routine.  */ 

(*SuperClass->composite_class.insert_child) (w,  args,  argcount); 

if  (!IsPane(w))  return; 

/*  I  I  I  Panes  will  be  added  in  the  order  they  are  created,  temporarilly  * 

if  (  pane->show_grip  =  =  TRUE  )  { 
CreateGrip (w) ; 

if  (pane->min  = =  PANED_GRIP_SIZE) 
pane->min  =  PaneSize (pane->grip,  IsVert ( (PanedWidget)  XtParent (w) ) ) ; 

} 
else  { 

if  (pane->min  ==  PANED_GRIP_SIZE) 
pane->min  =  1; 
pane->grip  =  NULL; 
} 

pane->size  =  0; 

pane->paned_ad justed_me  =  FALSE; 

}  /*  InsertChild  */ 

See  Also 

Composite (3),  Constraint^), 
delete  child(4). 
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query_geometry 


Name 

query_geometry  —  Core  method  called  when  a  widget  is  destroyed. 

Synopsis 

typedef  XtGeometryResult  (*XtGeometryHandler) (Widget,  XtWidgetGeometry  *); 
Widget  w; 

XtWidgetGeometry  *request; 
XtWidgetGeometry  * geometry_return; 

Arguments 

w  Specifies  the  widget 

request  Specifies  the  proposed  geometry. 

geome t ry_r e t urn 

Specifies  the  reply  geometry. 

Description 

The  query_geometry  method  is  expected  to  examine  the  bits  set  in 
request->request_mode,  evaluate  the  proposed  geometry  for  the  widget,  and  store  the 
result  in  geome try_ret urn  (setting  the  bits  in  geometry_return->request_mode 
corresponding  to  those  geometry  fields  that  it  cares  about).  If  the  proposed  geometry  change  is 
acceptable  without  modification,  the  query_geometry  method  should  return  xt- 
GeometryYes.  If  at  least  one  field  in  geometry_ret  urn  is  different  from  the  correspond 
ing  field  in  request  or  if  a  bit  was  set  in  geometry_return  that  was  not  set  in  request, 
the  query_geometry  method  should  return  xtGeometryAlmost.  If  the  preferred  geome 
try  is  identical  to  the  current  geometry,  the  query_geometry  method  should  return  xt- 
GeometryNo. 

After  calling  the  query_geometry  method  or  if  the  query_geometry  field  is  NULL,  Xt- 
Query  Geome  try  examines  all  the  unset  bits  in  eometry_return->request_mode  and  sets  the 
corresponding  fields  in  eometryjreturn  to  the  current  values  from  the  widget  instance.  If 
CWStackMode  is  not  set,  the  stack_mode  field  is  set  to  XtSMDontChange.  XtQuery- 
Geometry  returns  either  the  value  returned  by  the  query_geometry  method  or  Xt- 
GeometryYes  if  the  query_geometry  field  is  NULL. 

Therefore,  the  caller  can  interpret  a  return  of  XtGeometryYes  as  not  needing  to  evaluate  the 
contents  of  the  reply  and,  more  importantly,  not  needing  to  modify  its  layout  plans.  A  return  of 
XtGeometryAlmost  means  either  that  both  the  parent  and  the  child  expressed  interest  in  at 
least  one  common  field  and  the  child's  preference  does  not  match  the  parent's  intentions  or  that 
the  child  expressed  interest  in  a  field  that  the  parent  might  need  to  consider.  A  return  value  of 
xtGeometryNo  means  that  both  the  parent  and  the  child  expressed  interest  in  a  field  and  that 
the  child  suggests  that  the  field's  current  value  is  its  preferred  value.  In  addition,  whether  or 
not  the  caller  ignores  the  return  value  or  the  reply  mask,  it  is  guaranteed  that  the  geome - 
try_return  structure  contains  complete  geometry  information  for  the  child. 

Parents  are  expected  to  call  XtQueryGeometry  in  their  layout  routine  and  wherever  other 
information  is  significant  after  change_managed  has  been  called.  The  change_managed 
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method  may  assume  that  the  child's  current  geometry  is  its  preferred  geometry.  Thus,  the  child 
is  still  responsible  for  storing  values  into  its  own  geometry  during  its  initialize  method. 

Structures 

The  xtwidget Geometry  structure  is  similar,  but  not  identical,  to  the  corresponding  Xlib 
structure: 

typedef  unsigned  long  XtGeometryMask; 

typedef  struct  { 

XtGeometryMask  request_mode; 

Position  x,  y; 

Dimension   width,    height; 

Dimension   border_width; 

Widget    sibling; 

int    stack_mode; 
}    XtWidgetGeometry; 

The  request_mode  definitions  are  from  <Xll/X.h>: 


tdefine  CWX 

tdefine  CWY 

tdefine  CWWidth 

tdefine  CWHeight          (1«3) 

tdefine  CWBorderWidth 

tdefine  CWSibling 

tdefine  CWStackMode 


The  Xt  Intrinsics  also  support  the  following  value: 

tdef  ine         XtCWQueryOnly  (1«7) 

xtCWQueryOnly  indicates  that  the  corresponding  geometry  request  is  only  a  query  as  to  what 
would  happen  if  this  geometry  request  were  made  and  that  no  widgets  should  actually  be 
changed. 

XtMakeGeometryRequest,  like  the  Xlib  XConf  igureWindow  function,  uses 
request_mode  to  determine  which  fields  in  the  XtWidgetGeometry  structure  you  want 
to  specify. 

The  stack_mode  definitions  are  from  <Xll/X.h>: 

o 

i 

2 

3 
4 

The  Intrinsics  also  support  the  following  value: 

tdefine         XtSMDontChange        5 

For  precise  definitions  of  Above,  Below,  Toplf ,  Bottomif ,  and  Opposite,  see  the  refer 
ence  page  for  Conf  igureWindow  in  Volume  Two,  Xlib  Reference  Manual.  XtSMDont 
Change  indicates  that  the  widget  wants  its  current  stacking  order  preserved. 
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Above 

tdefine 

Below 

tdefine 

Toplf 

tdefine 

Bottomif 

tdefine 

Opposite 

Xt  -  Intrinsics  Methods  (continued)  query^geometry 

Examples 

The  following  is  the  query_geometry  method  of  the  BitmapEdit  widget  class: 

static   XtGeometryResult   QueryGeometry (w,    proposed,    answer) 

Widget   w; 

XtWidgetGeometry  *proposed,  *answer; 

{ 

BitmapEditWidget  cw  =  (BitmapEditWidget )  w; 

answer->request_mode  =  CWWidth  I  CWHeight; 

/*  initial  width  and  height  */ 

if  (cw->bitmapEdit .showAll  ==  True) 

answer->width  =  cw->bitmapEdit .pixmap_width_in_pixels; 
else 

answer->width  =  (cw->bitmapEdit .pixmap_width_in_pixels  > 

DEFAULTWIDTH)  ?  DEFAULTWIDTH  : 

static  XtGeometryResult  QueryGeometry (w,  proposed,  answer) 
Widget  w; 

XtWidgetGeometry  *proposed,  *answer; 
{ 

BitmapEditWidget  cw  =  (BitmapEditWidget)  w; 
answer->request_mode  =  CWWidth  I  CWHeight; 

/*  initial  width  and  height  */ 

if  (cw->bitmapEdit . showAll  ==  True) 

answer->width  =  cw->bitmapEdit . pixmap_width_in_pixels; 
else 

answer->width  =  (cw->bitmapEdit ,pixmap_width_in_pixels  > 
DEFAULTWIDTH)  ?  DEFAULTWIDTH  : 
cw->bitmapEdit .pixmap_width_in_pixels; 

if  (cw->bitmapEdit . showAll  ==  True) 

answer->height  =  cw->bitmapEdit .pixmap_height_in_pixels; 
else 

answer->height  =  (cw->bitmapEdit .pixmap_height_in_pixels  > 
DEFAULTWIDTH)  ?  DEFAULTWIDTH  : 
cw->bitmapEdit .pixmap_height_in_pixels; 

if  (   ( (proposed->request_mode  &  (CWWidth  I  CWHeight)) 

==  (CWWidth  |  CWHeight))  && 
proposed->width  ==  answer->width  && 
proposed->height  ==  answer->height ) 
return  XtGeometryYes; 

else  if  (answer->width  ==  cw->core .width  && 
answer->height  ==  cw->core. height) 
return  XtGeometryNo; 
else 

return  XtGeometryAlmost; 
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See  Also 

XtQueryGeometry  ( 1 ) , 
Composile(3). 
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— Xt  -  Intrinsics  Methods ' 

Name 

realize  —  Core  method  to  set  window  attributes  and  to  create  a  window. 

Synopsis 

typedef  void  ( *XtRealizeProc) (Widget,  XtValueMask,  XSetWindowAttributes  *) 
Widget  w; 

XtValueMask  value_mask; 
XSetWindowAttributes  *  at  tributes; 

Arguments 

w  Specifies  the  widget 

va l ue_mask        Specifies  which  fields  in  the  attributes  structure  to  use. 
attributes        Specifies  the  window  attributes  to  use  in  the  XCreateWindow  call. 

Description 

The  Intrinsics  invoke  the  Core  realize  method  of  each  widget  instance  when  the  application 
calls  xtRealizeWidget  on  the  application's  top-level  widget. 

The  Core  realize  method  must  set  window  attributes  for  the  window  and  create  the  widget's 
window.  value_mask  indicates  what  values  in  the  XSetWindowAttributes  structure 
are  used. 

XtRealizeWidget  fills  in  a  mask  and  a  corresponding  XSetWindowAttributes  struc 
ture.  It  sets  the  following  fields  based  on  information  in  the  widget's  Core  structure: 

•  background_jpixmap  (or  background_jpixel  if  background_pixmap  is  NULL) 
is  filled  in  from  the  corresponding  field. 

•  colormap  is  filled  in  from  the  corresponding  field. 

•  border_pixmap  (or  border_pixel  if  border_pixmap  is  NULL)  is  filled  in  from  the 
corresponding  field. 

•  event_mask  is  filled  in  based  on  which  event  handlers  are  registered,  which  event  trans 
lations  are  specified,  whether  expose  is  non-NULL,  and  whether  visible_interest  is 
True. 

•  bit_gravity  is  settoNorthWestGravity  if  the  expose  field  is  NULL. 

All  other  fields  in  attributes  (and  the  corresponding  bits  in  value_mask)  can  be  set  by 
the  realize  method. 

Note  that  because  realize  is  not  a  chained  operation,  the  widget  class's  realize  method 
must  update  the  XSetWindowAttributes  structure  with  all  the  appropriate  fields  from 
non-Core  superclasses. 

A  widget  class  can  inherit  its  realize  method  from  its  superclass  during  class  initialization 
by  specifying  xtlnheritRealize  for  the  realize  field.  The  realize  method  defined 
for  Core  calls  XtCreateWindow  with  the  passed  value_mask  and  attributes  and  with 
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windowClass  and  visual  set  to  CopyFromParent.  Both  CompositeWidgetClass 
and  ConstraintwidgetClass  inherit  this  realize  method,  and  most  new  widget  sub 
classes  can  do  the  same. 

The  most  common  noninherited  realize  methods  set  bit_gravity  in  value_mask  and 
attributes  to  the  appropriate  value  and  then  create  the  window.  For  example,  depending 
on  its  justification,  Label  sets  bit_gravity  to  WestGravity,  CenterGravity,  or 
EastGravity.  Consequently,  shrinking  it  just  moves  the  bits  appropriately,  and  no  Expose 
event  is  needed  for  repainting. 

If  a  composite  widget's  children  should  be  realized  in  a  particular  order  (typically  to  control 
the  stacking  order),  the  widget  should  call  XtRealizeWidget  on  its  children  itself  in  the 
appropriate  order  from  within  its  own  realize  method. 

Widgets  that  have  children  and  that  are  not  a  subclass  of  CompositeWidgetClass  are 
responsible  for  calling  XtRealizeWidget  on  their  children,  usually  from  within  the 
realize  method. 

Structures 

/*  Definitions  for  valuemask  argument.   These  control  which  fields  in 
*  XSetWindowAttributes  structure  should  be  used. 
*/ 


typedef  struct  { 

Pixmap  background_pixmap; 

unsigned  long  background_pixel; 

Pixmap  border_pixmap; 

unsigned  long  border_pixel; 

int  bit_gravity; 

int  win_gravity; 

int  backing_store; 

unsigned  long  backing_planes; 

unsigned  long  backing_pixel; 

Bool  save_under; 

long  event_mask; 

long  do_not_propagate_mask; 

Bool  override_redirect; 

Colormap  colormap; 

Cursor  cursor; 
}  XSetWindowAttributes; 


background  or  None  or  ParentRelative  *  / 

background  pixel  */ 

border  of  the  window  */ 

border  pixel  value  */ 

one  of  bit  gravity  values  */ 

one  of  the  window  gravity  values  */ 

NotUseful,  WhenMapped,  Always  */ 

planes  to  be  preserved  j,f  possible  */ 

value  to  use  in  restoring  planes  */ 

should  bits  under  be  saved  (popups)  */ 

set  of  events  that  should  be  saved  */ 

set  of  events  that  should  not  propagate 

boolean  value  for  override-redirect  */ 

colormap  to  be  associated  with  window  */ 

cursor  to  be  displayed  (or  None)  */ 


Examples 

The  following  is  the  realize  method  of  the  Athena  Paned  widget  class: 

static   void 

Realize (w,  valueMask,  attributes) 

Widget  w; 

Mask  *valueMask; 

XSetWindowAttributes  *attributes; 

PanedWidget  pw  =  (PanedWidget)  w; 
Widget  *  childP; 
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if    ( (attributes->cursor   =    (pw) ->paned. cursor)     !=   None) 
*valueMask    |=   CWCursor; 

(*SuperClass->core_class. realize)     (w,    valueMask,    attributes); 

/* 

*  Before  we  commit  the  new  locations  we  need  to 

*  realize  all  the  panes  and  their  grips. 
*/ 

ForAllPanes(pw,  child?)  { 

XtRealizeWidget (  *childP  ); 
if  (HasGrip  (*childP» 

XtRealizeWidget (  Panelnfo (*childP) ->grip  ) ; 
} 

Ref igureLocationsAndCommit (w) ; 
}  /*  Realize  */ 

See  Also 

XtCreateWindow  ( 1 ),  XtRealizeWidget  ( 1 ), 
Core(3). 
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v Xt  -  Intrinsics  Methods — 

Name 

resize  —  Core  method  called  when  a  widget  is  resized. 

Synopsis 

typedef  void  ( *XtWidgetProc) (Widget) ; 
Widget  w; 

Arguments 

w  Specifies  the  widget. 

Description 

The  resize  method  recalculates  the  layout  of  graphics  or  of  child  widgets,  modifying  internal 
data  as  needed.  The  x,  y,  width,  height  and  border_width  fields  of  the  widget  contain 
the  new  values. 

If  a  widget  always  draws  itself  according  to  the  size  placed  in  the  Core  height  and  width 
instance  variables,  it  does  not  need  a  resize  method.  If  this  is  the  case,  the  widget  can  spec 
ify  NULL  for  the  resize  field  in  its  class  record. 

Other  widgets,  however,  need  to  know  when  they  have  changed  size  so  that  they  can  change  the 
layout  of  their  displayed  data  to  match  the  new  size.  (For  example,  a  widget  may  choose  a  new 
smaller  font  if  its  size  has  decreased.) 

The  widget  must  treat  resize  as  a  command,  not  as  a  request.  A  widget  must  neither  resize 
itself  larger  from  its  resize  method,  nor  appeal  by  issuing  an  xtMakeGeometryRequest 
orXtMakeResizeRequest. 

When  a  parent  widget  is  resized,  it  should  reconfigure  its  children.  When  a  parent  resizes  a 
child,  it  updates  the  geometry  fields  in  the  widget,  configures  the  window  if  the  widget  is  real 
ized,  and  calls  the  child's  resize  method  to  notify  the  child. 

,,» 

Examples 

The  following  is  the  resize  method  of  the  BitmapEdit  widget  class: 

/*  ARGSUSED  */ 

static  void 

Resize (w) 

Widget  w; 

{ 

BitmapEditWidget  cw  =  (BitmapEditWidget)  w; 

/*  resize  does  nothing  unless  new  size  is  bigger  than  entire  pixmap  */ 

if  {  (cw->core  .width  >  cw->bitmapEdit  .  pixmap_width_in_pixeJ,s)  && 

(cw->core .height  >  cw->bitmapEdit .pixmap_height_in_pixels) )  { 
/* 

*  Calculate  the  maximum  cell  size  that  will  allow  the 

*  entire  bitmap  to  be  displayed. 
*/ 

Dimension  w_temp_cell_size_in_pixels,  h_temp_cell_size_in_pixels; 
Dimension  new_cell_size_in_pixels; 
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w   temp_cell_size_in_pixels   =   cw->core  .width   / 

cw->bitmapEdit  .pixmap_width_in_cells; 
h_temp_cell_size_in_pixels   =   cw->core  .height    / 

cw->bitmapEdit  .pixmap_height_in_cells; 

if    (w_temp_cell_size_in_pixels   <   h_temp_cell_size_in_pixels) 
new_cell_size_in_pixels   =   w_temp_cell_size_in_pixels; 

else 

new  cell_size_in_pixels  =  h_temp_cell_size_in_pixels; 

/*  if  size  change  mandates  a  new  pixmap,  make  one  */ 
if  (new_cell_size_in_pixels  !=  cw->bitmapEdit  .cell_size_in_pixels) 
ChangeCellSize  (cw,  new_cell_size_in_pixels)  ; 


See  Also 

XtConfigureWidget  (1  ), 
Core(3). 
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> Xt  -  Intrinsics  Methods — 

Name 

set_values  —  Core  method  for  processing  resource  changes. 

Synopsis 

typedef  Boolean  ( *XtSetValuesFunc) (Widget,  Widget,  Widget,  ArgList, 

Cardinal  *) ; 
Widget  current; 
Widget  request; 
Widget  new; 
ArgList  args; 
Cardinal  *num-args; 

Arguments 

current  Specifies  a  copy  of  the  widget  as  it  was  before  the  XtSetValues  call. 

request  Specifies  a  copy  of  the  widget  with  all  values  changed  as  asked  for  by  the 

XtSetValues  call  before  any  class  set_values  procedures  have  been 
called. 

new  Specifies  the  widget  with  the  new  values  that  are  actually  allowed. 

args  Specifies  the  argument  list  passed  to  XtSetValues. 

num_args  Specifies  the  count  of  arguments  in  the  argument  list. 

Description 

The  Core  set_values  method  is  responsible  for  checking  the  validity  of  resource  settings 
made  with  XtSetValues,  and  updating  any  nonresource  instance  structure  fields  (such  as 
GCs)  that  depend  on  resource  values. 

Like  the  initialize  method,  set_values  is  concerned  primarily  with  the  fields  defined 
by  its  own  class,  but  it  may  have  to  resolve  conflicts  with  its  superclass,  especially  over  width 
and  height. 

The  current,  request,  and  new  arguments  are  widget  instance  records  of  the  appropriate 
widget  class,  new  reflects  values  that  have  been  modified  by  superclass  set_values  meth 
ods,  request  reflects  changes  made  only  by  the  XtSetValues  call  itself,  current  was 
the  widget  instance  at  the  time  of  the  call,  reflecting  no  changes.  A  widget  can  refer  to 
request,  to  resolve  conflicts  between  current  and  new.  Any  changes  that  the  widget 
needs  to  make  should  be  made  to  new. 

Before  calling  the  set_values  method,  the  Intrinsics  modify  the  resources  of  the  request 
widget  according  to  the  contents  of  the  ArgList;  if  the  widget  names  all  of  its  resources  in 
the  class  resource  list,  the  contents  of  args  never  need  examining. 

An  XtSetValuesFunc  returns  a  Boolean  indicating  True  if  the  widget  should  be 
redisplayed  and  returns  False  otherwise.  set_values  methods  should  not  do  any  work  in 
response  to  anticipated  changes  in  geometry  because  XtSetValues  will  eventually  perform  a 
geometry  request.  The  request  might  be  denied.  If  the  widget  actually  changes  size  in  response 
to  an  XtSetValues,  its  resize  method  is  called.  Widgets  should  make  geometry-related 
changes  there. 
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An  xtSetValuesFunc  cannot  assume  that  the  widget  is  realized,  since  it  is  permissible  for 
an  application  to  call  xtSetValues  before  a  widget  is  realized. 

As  of  R4,  the  Core  set_values  method  can  contain  the  code  that  previously  appeared  in  the 
set_values_hook  method.  This  is  the  case  because  Core  set_values  is  now  passed  the 
argument  list  passed  to  XtSetValues. 

Examples 

The  following  is  the  set_values  method  of  the  BitmapEdit  widget  class: 

/*  ARGSUSED  */ 

static  Boolean 

SetValues (current,  request,  new,  args,  num_args) 

Widget  current,  request,  new; 

ArgList  args; 

Cardinal  *num_args; 

{ 

BitmapEditWidget  curcw  =  (BitmapEditWidget )  current; 

BitmapEditWidget  newcw  =  (BitmapEditWidget)  new; 

Boolean  do_redisplay  =  False; 

if  (curcw->bitmapEdit .foreground  !=  newcw->bitmapEdit . foreground)  { 

XtReleaseGC (curcw,  curcw->bitmapEdit .copy_gc) ; 

GetCopyGC (newcw) ; 

do_redisplay  =  True; 
} 

if  ( (curcw->bitmapEdit .cur_x  !=  newcw->bitmapEdit .cur_x)  I  I 

(curcw->bitmapEdit .cur_y  !=  newcw->bitmapEdit . cur_y) ) 
do_redisplay  =  True; 

if  (curcw->bitmapEdit .cell_size_in_pixels  != 

newcw->bitmapEdit .cell_size_in_pixels)  { 

ChangeCellSize (curcw,  newcw->bitmapEdit . cell_size_in_pixels) ; 
do_redisplay  =  True; 

} 

if  (curcw->bitmapEdit .pixmap_width_in_cells  != 

newcw->bitmapEdit .pixmap_width_in_cells)   { 
newcw->bitmapEdit .pixmap_width_in_cells  = 

curcw->bitmapEdit .pixmap_width_in_cells; 
XtWarning ("BitmapEdit:  pixmap_width_in_cells  cannot  be  \ 

set  by  XtSetValues. \n" ); 
} 

if  (curcw->bitmapEdit .pixmap_height_in_cells  != 

newcw->bitmapEdit .pixmap_height_in_cells)  { 
newcw->bitmapEdit ,pixmap_height_in_cells  = 

curcw->bitmapEdit .pixmap_height_in_cells; 

XtWarning ("BitmapEdit:  pixmap_height_in_cells  cannot  be  \ 
set  by  XtSetValues. \n" ); 
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return   do_redisplay; 


See  Also 

XtSetValues(l\ 

Core(3\ 

set_values_hook(4). 
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.    /  Constraint  set  values 

— Xt  -  Intrinsics  Methods ' 

Name 

Constraint  set_values  —  Constraint  method  for  processing  constraint  resource  changes. 

Synopsis 

typedef  Boolean  ( *XtSetValuesFunc) (Widget,  Widget,  Widget,  ArgList, 

Cardinal  *) ; 
Widget  current; 
Widget  request; 
Widget  new; 
ArgList  args; 
Cardinal  *num-args; 

Arguments 

current  Specifies  a  copy  of  the  widget  as  it  was  before  the  Xt  Set  Values  call. 

request  Specifies  a  copy  of  the  widget  with  all  values  changed  as  asked  for  by  the 

xtSetValues  call  before  any  class  set_values  procedures  have  been 
called. 

new  Specifies  the  widget  with  the  new  values  that  are  actually  allowed. 

args  Specifies  the  argument  list  passed  to  XtSetValues. 

num_args  Specifies  the  count  of  arguments  in  the  argument  list. 

Description 

The  Constraint  set_values  method  is  called  when  the  constraint  resources  of  its  children  are 
called.  It  is  checking  the  validity  of  these  new  settings,  and  triggering  a  new  layout  based  on 
the  new  settings. 

The  Constraint  set_values  method  operates  in  the  context  of  the  child.  This  means  its 
widget  arguments  are  instances  of  the  child,  not  the  parent,  even  though  the  method  itself  is 
part  of  the  parent's  code. 

The  current,  request,  and  new  arguments  are  widget  instance  records  of  the  appropriate 
widget  class,  new  reflects  values  that  have  been  modified  by  superclass  set_values  meth 
ods,  request  reflects  changes  made  only  by  the  XtSetValues  call  itself,  current  was 
the  widget  instance  at  the  time  of  the  call,  reflecting  no  changes.  A  widget  can  refer  to 
request,  to  resolve  conflicts  between  current  and  new.  Any  changes  that  the  widget 
needs  to  make  should  be  made  to  new. 

Before  calling  the  Constraint  set_values  method,  the  Intrinsics  modify  the  resources  of  the 
request  widget  according  to  the  contents  of  the  ArgList;  if  the  widget  names  all  of  its 
resources  in  the  class  resource  list,  the  contents  of  args  never  need  examining. 

An  xtSetValuesFunc  returns  a  Boolean  value  of  True  if  the  widget  should  be  redisplayed 
and  a  value  of  False  otherwise.  Constraint  set_values  methods  should  not  do  any  work  in 
response  to  anticipated  changes  in  geometry  because  XtSetValues  will  eventually  perform  a 
geometry  request  The  request  might  be  denied.  If  the  widget  actually  changes  size  in  response 
to  an  XtSetValues,  its  resize  method  is  called.  Widgets  should  make  geometry-related 
changes  there. 
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An  xtSetValuesFunc  cannot  assume  that  the  widget  is  realized,  since  it  is  permissible  for 
an  application  to  call  Xt  Set  Values  before  a  widget  is  realized. 

Examples 

The  following  is  the  Constraint  set_values  method  of  the  Athena  Form  widget  class: 

/*  ARGSUSED  */ 

static  Boolean  ConstraintSetValues  (current,  request,  new) 

Widget  current,  request,  new; 
{ 

return  (  FALSE  )  ; 


See  Also 

XtSetVaIues(l\ 
Constraint®),  Core®), 
set_values(4),  set_values_hook(4). 
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/  set  values  almost 

— Xt  -  Intrinsics  Methods ' 

Name 

set_values_almost  —  Core  method  to  negotiate  compromise  geometries. 

Synopsis 

typedef  void  ( *XtAlmostProc) (Widget,  Widget,  XtWidgetGeometry  *,  XtWidget- 

Geometry  *) ; 
Widget  old; 
Widget  new; 

XtWidgetGeometry  *request; 
XtWidgetGeometry  * reply; 

Arguments 

old  Specifies  a  copy  of  the  object  as  it  was  before  the  Xt  Set  Values  call. 

new  Specifies  the  object  instance  record. 

request  Specifies  the  original  geometry  request  that  was  sent  to  the  geometry  man 

ager  that  returned  XtGeometryAlmost. 

reply  Specifies  the  compromise  geometry  that  was  returned  by  the  geometry  man 

ager  that  returned  XtGeometryAlmost. 

Description 

The  purpose  of  the  set_values_almost  method  is  to  negotiate  a  compromise  geometry 
with  the  parent 

A  widget's  set_values_almost  method  is  called  when  a  client  tries  to  set  a  widget's 
geometry  by  means  of  a  call  to  XtSetValues  and  the  geometry  manager  cannot  satisfy  the 
request  but  instead  returns  XtGeometryAlmost  and  a  compromise  geometry.  The 
set_values_almost  method  takes  the  original  geometry  and  the  compromise  geometry 
and  determines  whether  the  compromise  is  acceptable  or  a  different  compromise  might  work. 
It  returns  its  results  in  the  new  parameter,  which  is  then  sent  back  to  the  geometry  manager  for 
another  try. 

Most  classes  inherit  the  set_values_almost  method  from  their  superclass  by  specifying 
XtlnheritSetValuesAlmost  in  the  class  initialization.  The  Core  set_values_ 
almost  method  always  accepts  the  compromise  suggested. 

See  Chapter  11,  Geometry  Management,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming 
Manual. 

Structures 

The  XtWidgetGeometry  structure  is  similar,  but  not  identical,  to  the  corresponding  Xlib 
structure: 

typedef  unsigned  long  XtGeometryMask; 

typedef  struct  { 

XtGeometryMask  request_mode; 
Position  x,  y; 
Dimension  width,  height; 
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Dimension   border_width; 
Widget    sibling; 
int    stack_mode; 
}    XtWidgetGeometry; 

The  request  mode  definitions  are  from  <Xll/X.h>: 


tdefine  CWX 

tdefine  CWY  (1«1) 

#define  CWWidth 

#define  CWHeight 

tdefine  CWBorderWidth 

#define  CWSibling 

tdefine  CWStackMode 


The  Xt  Intrinsics  also  support  the  following  value: 

#define         XtCWQueryOnly  (1«7) 

XtCWQueryOnly  indicates  that  the  corresponding  geometry  request  is  only  a  query  as  to  what 
would  happen  if  this  geometry  request  were  made  and  that  no  widgets  should  actually  be 
changed. 

XtMakeGeometryRequest,  like  the  Xlib  XConf  igureWindow  function,  uses 
request_mode  to  determine  which  fields  in  the  XtWidgetGeometry  structure  you  want 
to  specify. 

The  stack_mode  definitions  are  from  <Xll/X.h>: 

o 
i 

2 

3 

4 

The  Intrinsics  also  support  the  following  value: 

tdefine         XtSMDontChange         5 

For  precise  definitions  of  Above,  Below,  Toplf ,  Bottomlf ,  and  Opposite,  see  the  refer 
ence  page  for  Conf  igureWindow  in  Volume  Two,  Xlib  Reference  Manual.  XtSMDont 
Change  indicates  that  the  widget  wants  its  current  stacking  order  preserved. 

See  Also 

CoreQ), 

set_values(4),  Constraint  set_values(4). 


#def  ine 

Above 

#def  ine 

Below 

#def  ine 

Toplf 

#def  ine 

Bottomlf 

#define 

Opposite 
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— Xt  -  Intrinsics  Methods ' 

Name 

set_values_hook  —  Core  method  for  processing  subpart  resources. 

Synopsis 

typedef  Boolean  ( *XtArgsFunc) (Widget,  ArgList,  Cardinal  *); 
Widget  w; 
ArgList  args; 
Cardinal  *num_args; 

Arguments 

w  Specifies  the  widget  whose  nonwidget  resource  values  are  to  be  changed. 

args  Specifies  the  argument  list  that  was  passed  to  XtSetValues. 

num_args  Specifies  the  number  of  arguments  in  the  argument  list. 

Description 

The  set_values_hook  method  is  obsolete,  but  still  called  (immediately  after  the  Core 
set_values  method)  for  backwards  compatibility.  Its  job  was  to  set  resources  values  of  sub- 
parts  by  called  xtSetSubresources,  but  this  job  can  now  be  handled  by  the  Core 
set_values  method,  since  the  argument  list  of  set_values_hook  has  been  added  to 
Core  set_values  inR4. 

The  set_values_hook  method  returns  a  Boolean  indicating  whether,  based  on  the  values 
passed  in  args,  the  widget  needs  to  be  redrawn.  To  set  the  actual  subvalues  of  the  nonwidget 
data,  the  widget  should  call  XtSetSubvalues  and  pass  the  appropriate  resource  list. 

The  set_values_hook  method  is  similar  to  the  set_values  method,  except  that  it  is 
passed  only  the  current  widget  instance  structure,  instead  of  the  old  and  new  copies  of  the 
widget  instance  structure  which  are  passed  to  set_values.  As  a  result, 
set_values_hook  needs  to  use  a  different  technique  for  comparing  the  current  subresource 
values  with  the  values  set  by  XtSetValues. 

There  are  two  ways  to  do  this.  One  is  to  loop  through  the  widget's  resource  list,  using  strcmp 
to  compare  each  resource  name  in  the  argument  list  with  the  subresource  names,  and  then  com 
paring  each  argument  value  with  the  current  value  of  the  subresource. 

The  other  way  is  to  copy  the  instance  structure  passed  in  using  bcopy  (after  allocating  mem 
ory  for  the  new  copy  with  xtNew,  described  in  Chapter  13,  Miscellaneous  Toolkit  Program 
ming  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual).  Then  call  Xt 
SetSubvalues  to  set  the  actual  values  to  those  in  the  argument  list.  After  this  process,  you 
can  compare  the  old  and  new  values  the  same  way  this  is  done  in  the  set_values  method. 
But  since  the  Core  set_yalues  method  is  now  called  with  the  arglist,  you  can  avoid  having 
to  do  this  bcopy  by  moving  your  code  into  Core  set_values. 

Similarly,  initialize_hook  is  also  obsolete  beginning  in  R4:  use  initialize  instead. 
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Structures 

Arg  is  defined  as  follows  in  <X11  /Intrinsic.  h>: 

typedef  struct  { 

String  name; 

XtArgVal   value; 
}    Argf    *ArgList; 

Examples 

The  following  is  the  set_values_hook  method  of  the  Athena  SimpleMenu  widget  class: 

static  Boolean 

SetValuesHook  (w,  arglist,  num_args) 

Widget  w; 

ArgList  arglist; 

Cardinal  *num_args; 

{ 

register  Cardinal  i; 

Dimension  width,  height; 

width  =  w->core  .  width; 
height  =  w->core  .height; 

for  (  i  =  0  ;  i  <  *num_args  ;  i++)  { 
if  (  streq  (arglist  [  i]  .name,  XtNwidth)  ) 

width  =  (Dimension)  arglist  [  i]  .value; 
if  (  streq  (arglist  [  i]  .name,  XtNheight)  ) 

height  =  (Dimension)  arglist  [i]  .value; 
} 

if  ((width  !=  w->core  .width)  ||  (height  !=  w->core  .  height  )) 
MakeSetValuesRequest  (w,  width,  height);  y, 

return  (FALSE)  ; 


See  Also 

XtCreateWidget(\\  XtSetSubvalues(\\  XtSetValues(l), 

Core(3\ 

set_values(4). 
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Athena  Classes 


This  section  contains  alphabetically-organized  reference  pages  for  the 
Athena  widgets.  This  widget  set  is  not  part  of  the  Intrinsics  but  was  devel 
oped  by  MIT's  Project  Athena  to  demonstrate  their  use.  It  is  documented 
here,  since  the  Athena  Widgets  are  used  in  the  examples  for  Volume  4. 

Each  reference  page  provides  a  description  of  the  widget  class  and  docu 
ments  the  include  files  for  the  widget,  its  class  hierarchy,  resources,  transla 
tions  and  actions,  and  its  programmatic  interface,  including  both  the  Intrinsics 
calls  to  create  or  manage  the  widget  and  any  functions  the  widget  itself 
exports. 

In  This  Section: 


Box 
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Dialog 

Form 

Grip 

Label 

List 

Menu  Button 
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Scrollbar 
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Box 


Name 

Box  widget  —  geometry-managing  box  widget 

Synopsis 

#include  <Xll/StringDef s .h> 

#include  <Xll/Intrinsic ,h> 

tinclude  <Xll/Xaw/Box.h> 

widget  =  XtCreateWidget (name,  boxWidgetClass, . . . ) ; 

Class  Hierarchy 

Core  — >  Composite  — »  Box 

Description 

The  Box  widget  provides  geometry  management  of  arbitrary  widgets  in  a  box  of  a  specified 
dimension.  Box  moves  but  does  not  resize  its  children.  The  children  are  rearranged  when  the 
Box  is  resized,  when  its  children  are  resized,  or  when  children  are  managed  or  unmanaged. 
The  Box  widget  always  attempts  to  pack  its  children  as  closely  as  possible  within  the  geometry 
allowed  by  its  parent. 

Box  widgets  are  commonly  used  to  manage  a  related  set  of  Command  widgets  and  are  fre 
quently  called  ButtonBox  widgets,  but  the  children  are  not  limited  to  buttons. 

The  children  are  arranged  on  a  background  that  has  its  own  specified  dimensions  and  color. 

Resources 

When  creating  a  Box  widget  instance,  the  following  resources  are  retrieved  from  the  argument 
list  or  from  the  resource  database: 


Name 

Type 

Default 

Description 

XtNaccelerators 

Accelerator-Table 

NULL 

List  of  event-to-action  bindings  to  be  exe 
cuted  by  this  widget,  even  though  the  event 
occurred  in  another  widget 

XtNancestor- 
Sensitive 

Boolean 

True 

Sensitivity   state  of  the  ancestors   of  this 
widget:  a  widget  is  insensitive  if  either  it  or 
any  of  its  ancestors  is  insensitive 

XtNbackground 

Pixel 

XtDefault- 
Background 

Window  background  color 

XtNbackground- 
Pixmap 

Plxmap 

XtUnspecified- 
Pixmap 

Window  background  pixmap 

XtNborderColor 

Pixel 

XtDefault- 

Window  border  color 

Foreground 

XtNborderPixmap 

Pixmap 

XtUnspecified- 
Pixmap 

Window  border  pixmap 

XtNborderWidth 

Dimension 

1 

Border  width  on  button  box 

XtNchildren 

WidgetList 

NULL 

List  of  all  this  composite  widget's  current 
children 

XtNcolormap 

Colormap 

Parent's  colormap 

Colormap  that  this  widget  will  use 
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Name 

Type 

Default 

Description 

XtNdepth 

int 

Parent's  depth 

Depth  of  this  widget's  window 

XtNdestroy- 

XtCallbackList 

NULL 

Callbacks  forXtDestroyWidget 

Callback 

XtNheight 

Dimension 

See  below 

Viewing  height  of  inner  window 

XtNhSpace 

Dimension 

4 

Pixel  distance  left  and  right  of  children 

XtNmappedWhen- 

Boolean 

TRUE 

Whether  XtMapWidget  is  automatic 

Managed 

XtNnumChildren 

Cardinal 

0 

Number  of  children  in  this  composite  widget 

XtNorientation 

Orientation 

XtOrientVertical 

See  below 

XtNscreen 

Screen 

Parent's  screen 

Screen  on  which  this  widget  is  displayed 

XtNsensitive 

Boolean 

TRUE 

Whether  widget  receives  input 

XtNtranslations 

TranslationTable 

NULL 

Event-to-action  translations 

XtNvSpace 

Dimension 

4 

Pixel  distance  top  and  bottom  of  children 

XtNwidth 

Dimension 

See  below 

Viewing  width  of  inner  window 

XtNx 

Position 

0 

x  coordinate  in  pixels 

XtNy 

Position 

0 

y  coordinate  in  pixels 

The  Box  widget  positions  its  children  in  rows  with  XtNhSpace  pixels  to  the  left  and  right  of 
each  child  and  XtNvSpace  pixels  between  rows.  If  the  Box  width  is  not  specified,  the  Box 
widget  uses  the  width  of  the  widest  child.  Each  time  a  child  is  managed  or  unmanaged,  the  Box 
widget  attempts  to  reposition  the  remaining  children  to  compact  the  box.  Children  are  posi 
tioned  in  order,  from  left  to  right  and  from  top  to  bottom.  The  packing  algorithm  used  depends 
on  the  value  of  XtNorientation,  which  is  described  below.  After  positioning  all  children, 
the  Box  widget  attempts  to  shrink  its  own  size  to  the  minimum  dimensions  required  for  the  lay 
out. 

The  XtNorientation  resource  specifies  whether  the  preferred  shape , of  the  box  (i.e.  the 
result  returned  by  the  query_geometry  class  method)  is  tall  and  narrow  (XawOrient- 
Vertical)  or  short  and  wide  (XawOrientHorizontal).  When  the  Box  is  a  child  of  a 
parent  which  enforces  width  constraints,  it  is  usually  better  to  specify  XawOrientVertical 
(the  default).  When  the  parent  enforces  height  constraints,  it  is  usually  better  to  specify  Xaw 
OrientHorizontal. 

The  packing  algorithm  used  by  the  Box  widget  depends  on  the  value  of  XtNorientation. 
The  two  possibilities  are: 

XtOrientVertical 

When  the  next  child  does  not  fit  on  the  current  row,  a  new  row  is  started.  If  a  child  is 
wider  than  the  width  of  the  box,  the  box  will  request  a  larger  width  from  its  parent  and 
will  begin  the  layout  process  from  the  beginning  if  a  new  width  is  granted. 

XtOrientHorizontal 

When  the  next  child  does  not  fit  in  the  current  column,  a  new  column  is  started.  If  a  child 
is  taller  than  the  height  of  the  box,  the  box  will  request  a  larger  height  from  its  parent  and 
will  begin  the  layout  process  from  the  beginning  if  a  new  height  is  granted. 
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Programmatic  Interface 

To  create  a  Box  widget  instance,  use  xtCreateWidget  and  specify  the  class  variable 

boxWidgetClass. 

To  add  a  child  to  the  Box,  use  XtCreateWidget  and  specify  the  widget  ID  of  the  Box 

as  the  parent  of  the  new  widget 

To  remove  a  child  from  a  Box,  use  XtUnmanageChild  or  XtDestroyWidget  and 

specify  the  widget  ID  of  the  child. 

To  destroy  a  Box  widget  instance,  use  XtDestroyWidget  and  specify  the  widget  ID  of 
the  Box  widget.  All  the  children  of  this  box  are  destroyed  automatically  at  the  same  time. 

See  Also 

Core(3),  Composite®),  Command^). 
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Name 

Command  widget  —  command  button  activated  by  pointer  click. 

Synopsis 

#include  <Xll/StringDef s . h> 

#include  <Xll/Intrinsic .h> 

#include  <Xll/Xaw/Command.h> 

widget  =  XtCreateWidget (name,  commandWidgetClass, . 


Class  Hierarchy 

Core  — »  Simple 


Label  ->  Command 


Description 

The  Command  widget  is  an  area,  often  rectangular,  that  contains  a  text  or  pixmap  label.  This 
selectable  area  is  sometimes  referred  to  as  a  "button".  When  the  pointer  cursor  is  on  the  button, 
the  button  border  is  highlighted  to  indicate  that  the  button  is  ready  for  selection.  When  pointer 
button  1  is  pressed,  the  command  widget  indicates  that  it  has  been  selected  by  reversing  its 
foreground  and  background  colors.  When  the  pointer  button  is  released,  the  Command 
widget's  notify  action  is  invoked,  calling  all  functions  on  its  callback  list. 

Resources 

When  creating  a  Command  widget  instance,  the  following  resources  are  retrieved  from  the 
argument  list  or  from  the  resource  database: 


Name 

Type 

Default 

Description 

XtNaccelerators 

Accel  eratorTable 

NULL 

List  of  event-to-action  bindings  to  be 
executed  by  this  widget,  even  though 
the  event  occurred  in  another  widget 

XtNancestor- 
Sensitive 

Boolean 

True 

Sensitivity  state  of  the  ancestors  of 
this  widget:  a  widget  is  insensitive  if 
either  it  or  any  of  its  ancestors  is 

insensitive 

XtNbackground 

Pixel 

XtDefault- 
Background 

Window  background  color 

XtNbackground- 
Pixmap 

Pixmap 

XtUnspecified- 
Pixmap 

Window  background  pixmap 

XtNbitmap 

Pixmap 

None 

Pixmap  to  display  in  place  of  the 
label 

XtNborderColor 

Pixel 

XtDefault- 

Window  border  color 

Foreground 

XtNborderPixmap 

Pixmap 

XtUnspecified- 
Pixmap 

Window  border  pixmap 

XtNborderWidth 

Dimension 

1 

Width  of  button  border 

XtNcallback 

XtCallbackList 

NULL 

Callback  for  button  select 

XtNcolormap 

Colormap 

Parent's  colormap 

Colormap  that  this  widget  will  use 

XtNcorner  Round- 

Dimension 

25 

See  below 

Percent 

XtNcursor 

Cursor 

None 

Pointer  cursor 
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Name 

Type 

Default 

Description 

XtNdepth 

int 

Parent's  depth 

Depth  of  this  widget's  window 

XtNdestroy- 
Callback 

XtCallbackList 

NULL 

Callbacks  forXtDestroyWidget 

XtNfont 

XFont  Struct* 

XtDefaultFont 

Label  font 

XtNforeground 

Pixel 

XtDefault- 
Foreground 

Foreground  color 

XtNheight 

Dimension 

font  height  +  2  * 

XtNinternalHeight 

Button  height 

XtNhighlight- 
Thickness 

Dimension 

2 

Width  of  border  to  be  highlighted 

XtNinsensitive- 

Pixmap 

GrayPixmap 

Border  when  not  sensitive 

Border 

XtNinternal- 
Height 

Dimension 

2 

Internal  border  height  for  highlight 
ing 

XtNinternalWidth 

Dimension 

4 

Internal  border  width  for  highlight 

ing 

XtNjustify 

Xt  Justify 

XtJustifyCenter 

Type  of  text  alignment 

XtNlabel 

String 

name  of  widget 

Button  label 

XtNmappedWhen- 
Managed 

Boolean 

TRUE 

Whether  xtMapWidget  is  automatic 

XtNresize 

Boolean 

TRUE 

Whether  to  auto-resize  in  Set  Values 

XtNscreen 

Screen 

Parent's  screen 

Screen    on    which    this    widget    is 
displayed:    this    is    not    a    sellable 

resource 

XtNsensitive 

Boolean 

TRUE 

Whether  widget  receives  input 

XtNshapeStyle 

ShapeStyle 

Rectangle 

See  below 

XtNtranslations 

Translation- 

See  below 

Event-to-action  translations 

Table 

XtNwidth 

Dimension 

XtNlabel  width  +  2  * 

Button  width 

XtNinternalWidth 

XtNx 

Position 

0 

x  coordinate  in  pixels 

XtNy 

Position 

0 

y  coordinate  in  pixels 

Note  that  the  Command  widget  supports  two  callback  lists:  xtNdestroyCallback  and 
XtNcallback.  The  notify  action  executes  the  callbacks  on  the  XtNcallback  list.  The 
call_data  argument  is  unused. 

The  new  resources  (not  inherited  from  superclasses)  associated  with  the  Command  widget  are: 

XtNcallback 

The  callback  list  executed  by  the  notify  action. 

XtNhighlight Thickness 

The  thickness  of  the  line  drawn  by  the  highlight  action. 

XtNshapeStyle 

Nonrectangular  buttons  may  be  created  using  this  resource.  Nonrectangular  buttons  are 
supported  only  on  a  server  that  supports  the  Shape    Extension.   If  nonrectangular 
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buttons  are  specified  for  a  server  lacking  this  extension,  the  shape  is  ignored  and  the  widg 
ets  will  be  rectangular.  The  following  shapes  are  currently  supported:  XmuShape- 
Rectangle,  XmuShapeOval,  XmuShapeEllipse,  and  XmuShapeRounded- 
Rectangle. 

XtNcornerRoundPercent 

When  a  ShapeStyle  of  roundedRectangle  is  used,  this  resource  controls  the  radius 
of  the  rounded  corner.  The  radius  of  the  rounded  comers  is  specified  as  a  percentage  of  the 
length  of  the  shortest  side  of  the  widget 

Translations  and  Actions 

The  following  are  the  default  translation  bindings  that  are  used  by  the  Command  widget: 

<EnterWindow> : highlight ( ) 
<LeaveWindow> : reset ( ) 
<BtnlDown>:set { ) 
<BtnlUp>: notify ( )  unset () 

With  these  bindings,  the  user  can  cancel  the  action  before  releasing  the  button  by  moving  the 
pointer  out  of  the  Command  widget 

The  Command  widget  supports  the  following  actions: 

Switching  the  button  between  the  foreground  and  background  colors  with  set  and 
unset. 

•         Processing  application  callbacks  with  notify. 

Switching  the  internal  border  between  highlighted  and  unhighlighted  states  with  high 
light  and  unhighlight. 

The  full  list  of  actions  supported  by  Command  is  as  follows: 

highlightQ  Displays  the  internal  highlight  border  in  the  color  (XtNf  oreground  or 
XtNbackground)  that  contrasts  with  the  interior  color  of  the  Command 
widget  The  conditions  WhenUnset  and  Always  are  understood  by  this 
action  procedure.  If  no  argument  is  passed,  WhenUnset  is  assumed. 

unhighlightQ  Displays  the  internal  highlight  border  in  the  color  (XtNf  oreground  or 
XtNbackground)  that  matches  the  interior  color  of  the  Command 
widget 

set()  Enters  the  set  state,  in  which  notify  is  possible  and  displays  the  inter 

ior  of  the  button,  including  the  highlight  border,  in  the  foreground  color. 
The  label  is  displayed  in  the  background  color. 

unset( )  Cancels  the  set  state  and  displays  the  interior  of  the  button,  including  the 

highlight  border,  in  the  background  color.  The  label  is  displayed  in  the 
foreground  color. 

resetQ  Cancels  any  set  or  highlight  and  displays  the  interior  of  the  button 

in  the  background  color,  with  the  label  displayed  in  the  foreground  color. 
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notify()  Executes  the  callback  list  specified  by  xtNcallback,  if  executed  in  the 

set  state.  The  value  of  the  call_data  argument  is  undefined. 

Programmatic  Interface 

•       To  create  a  Command  widget  instance,  use  xtCreateWidget  and  specify  the  class  vari 
able  commandWidgetClass. 

To  destroy  a  Command  widget  instance,  use  xtDestroyWidget  and  specify  the  widget 
ID  of  the  Command  widget. 

See  Also 

Box(5\  Label(5),  MenuButton(5). 
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Name 

Dialog  widget  —  dialog  box  widget. 

Synopsis 

tinclude  <Xll/StringDefs . h> 

#include  <Xll/Intrinsic .h> 

tinclude  <Xll/Xaw/Dialog . h> 

widget  =  XtCreateWidget (name,  dialogWidgetClass,  .  .  . )  ; 

Class  Hierarchy 

Core  ->  Composite  ->  Constraint  ->  Form  ->  Dialog 

Description 

The  Dialog  widget  implements  a  commonly  used  interaction  semantic  to  prompt  for  auxiliary 
input  from  a  user.  For  example,  you  can  use  a  Dialog  widget  when  an  application  requires  a 
small  piece  of  information,  such  as  a  filename,  from  the  user.  A  Dialog  widget  is  simply  a  spe 
cial  case  of  the  Form  widget  that  provides  a  convenient  way  to  create  a  preconfigured  form. 

The  typical  Dialog  widget  contains  three  areas.  The  first  line  contains  a  description  of  the  func 
tion  of  the  Dialog  widget,  for  example,  the  string  Filename:.  The  second  line  contains  an  area 
into  which  the  user  types  input.  The  third  line  can  contain  buttons  that  let  the  user  confirm  or 
cancel  the  Dialog  input.  Any  of  these  areas  may  be  omitted  by  the  application. 

Resources 

When  creating  a  Dialog  widget  instance,  the  following  resources  are  retrieved  from  the  argu 
ment  list  or  from  the  resource  database: 


Name 

Type 

Default 

Description 

XtNaccelerators 

Accelerator-Table 

NULL 

List  of  event-to-action  bindings  to  be  exe 
cuted  by  this  widget,  even  though  the  event 
occurred  in  another  widget 

XtNancestor- 
Sensitive 

Boolean 

True 

Sensitivity   state   of  the  ancestors   of  this 
widget:  a  widget  is  insensitive  if  either  it  or 
any  of  its  ancestors  is  insensitive 

XtNbackground 

Pixel 

XtDefault- 
Background 

Window  background  color 

XtNbackground- 
Pixmap 

P  ixmap 

XtUnspecified- 
P  ixmap 

Window  background  pixmap 

XtNborderColor 

Pixel 

XtDefault- 

Window  border  color 

Foreground 

XtNborder  P  ixmap 

P  ixmap 

XtUnspecified- 
P  ixmap 

Window  border  pixmap 

XtNborderWidth 

Dimension 

1 

Width  of  border  in  pixels 

XtNchildren 

WidgetList 

NULL 

List  of  all  this  composite  widget's  current 
children 

XtNcolormap 

Colormap 

Parent's  colormap 

Colormap  that  this  widget  will  use 
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Name 

Type 

Default 

Description 

XtNdefault- 

int 

4 

Default  value  for  XtNhorizDi  stance  and 

Distance 

XtNvertDistance 

XtNdepth 

int 

Parent's  depth 

Depth  of  this  widget's  window 

XtNdestroy- 

XtCallbackList 

NULL 

Callbacks  forXtDestroyWidget 

Callback 

XtNheight 

Dimension 

Computed 
at  realize 

Height  of  dialog 

XtNicon 

Pixmap 

None 

See  below 

XtNlabel 

String 

"label" 

See  below 

XtNmappedWhen- 

Boolean 

TRUE 

Whether  xtMapWidget  is  automatic 

Managed 

XtNnumChildren 

Cardinal 

0 

Number  of  children  in  this  composite  widget 

XtNscreen 

Screen 

Parent's  screen 

Screen  on  which  this  widget  is  displayed 

XtNsensltive 

Boolean 

TRUE 

Whether  widget  receives  input 

XtNtranslations 

TranslationTable 

NULL 

Event-to-action  translations 

XtNvalue 

char* 

NULL 

Pointer  to  default  string 

XtNwidth 

Dimension 

Computed 
at  realize 

Width  of  dialog 

XtNx 

Position 

0 

x  coordinate  in  pixels 

XtNy 

Position 

0 

y  coordinate  in  pixels 

The  instance  name  of  the  label  widget  within  the  Dialog  widget  is  label,  and  the  instance  name 
of  the  Dialog  value  widget  is  value. 

The  new  resources  (not  inherited  from  superclasses)  associated  with  the  Dialog  widget  are: 

XtNicon 

A  pixmap  image  to  be  displayed  immediately  to  the  left  of  the  Dialog  widget's  label. 

XtNlabel 

A  Latin  1  string  to  be  displayed  at  the  top  of  the  Dialog  widget. 

XtNvalue 

An  initial  value  for  the  string  field  into  which  the  user  will  enter  text.  By  default,  no  text 
entry  field  is  available  to  the  user.  Specifying  an  initial  value  for  value  activates  the  text 
entry  field.  If  string  input  is  desired  but  no  initial  value  is  to  be  specified,  then  set  this 
resource  to  ""  (empty  string). 

Programmatic  Interface 

To  create  a  Dialog  widget  instance,  use  xtCreateWidget  and  specify  the  class  variable 
dialogWidget Class. 

•  To  add  a  child  button  to  the  Dialog  box,  use  XtCreateWidget  and  specify  the  widget 
ID  of  the  previously  created  Dialog  box  as  the  parent  of  each  child.  When  creating  but 
tons,  you  do  not  have  to  specify  form  constraints.  The  Dialog  box  will  automatically  add 
the  constraints. 
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To  return  the  character  string  in  the  text  field,  use: 

char  *XawDialogGetValueString (w) 
Widget  w; 

where  w  specifies  the  widget  ID  of  the  Dialog  box. 

If  a  string  was  specified  in  the  xtNvalue  resource,  the  Dialog  widget  will  store  the  input 
directly  into  the  string. 

To  remove  a  child  button  from  the  Dialog  box,  use  XtUnmanageChild  or  xt- 
DestroyWidget  and  specify  the  widget  ID  of  the  child. 

•  To  destroy  a  Dialog  widget  instance,  use  XtDestroyWidget  and  specify  the  widget  ID 
of  the  Dialog  widget.  All  children  of  the  Dialog  are  destroyed  automatically  at  the  same 
time. 

See  Also 

Command(5),  Form(5\  Text(5). 
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Form 


Name 

Form  widget  —  geometry-managing  widget  implementing  constraints  on  children. 

Synopsis 

#include  <Xll/StringDef s .h> 

tinclude  <Xll/Intrinsic ,h> 

tinclude  <Xll/Xaw/Form.h> 

widget  =  XtCreateWidget (name,  f ormWidget Class, ...); 

Class  Hierarchy 

Core  — »  Composite  — >  Constraint  ->  Form 

Description 

The  Form  widget  can  contain  an  arbitrary  number  of  children  of  any  class.  The  Form  provides 
geometry  management  for  its  children,  including  individual  control  of  the  position  of  each 
child.  The  initial  positions  of  the  children  may  be  computed  relative  to  the  positions  of  other 
children.  When  the  Form  is  resized,  it  computes  new  positions  and  sizes  for  its  children.  This 
computation  is  based  upon  information  provided  as  constraints  when  each  child  is  added  to  the 
Form. 

Resources 

When  creating  a  Form  widget  instance,  the  following  resources  are  retrieved  from  the  argument 
list  or  from  the  resource  database: 


Name 

Type 

Default 

Description 

XtNaccelerators 

Accelerator  Table 

NULL 

List  of  event-to-action  bindings  to  be 

executed  by  this  widget,  even  though 

the  event  occurred  in  another  widget 

XtNancestor- 

Boolean 

True 

Sensitivity  state  of  the  ancestors  of  this 

Sensitive 

widget:  a  widget  is  insensitive  if  either 

it  or  any  of  its  ancestors  is  insensitive 

XtNbackground 

Pixel 

XtDefault- 

Window  background  color 

Background 

XtNback.gr  ound- 

Pixmap 

XtUnspecif  ied- 

Window  background  pixmap 

Pixmap 

Pixmap 

XtNborderColor 

Pixel 

XtDefault- 

Window  border  color 

Foreground 

XtNborderPixmap 

Pixmap 

XtUnspecified- 

Window  border  pixmap 

Pixmap 

XtNborderWidth 

Dimension 

1 

Width  of  border  in  pixels 

XtNchildren 

WidgetList 

NULL 

List  of  all  this  composite  widget's  cur 

rent  children 

XtNcolormap 

Colormap 

Parent's  colormap 

Colormap  that  this  widget  will  use 

XtNdefault- 

int 

4 

Default  value  for  XtNhorizDi  stance 

Distance 

and  XtNvert  Distance 

XtNdepth 

int 

Parent's  depth 

Depth  of  this  widget's  window 

X  Toolkit  Intrinsics  Reference  Manual 


531 


Form 


(continued) 


Xt  -  Athena  Classes 


Name 

Type 

Default 

Description 

XtNdestroy- 

Callback 

XtCallbackList 

NULL 

Callbacks  for  XtDestroyWidget 

XtNheight 

Dimension 

Computed 
at  realize 

Height  of  form 

XtNmappedWhen- 
Managed 

Boolean 

TRUE 

Whether  xtMapWidget  is  automatic 

XtNnumChildren 

Cardinal 

0 

Number  of  children  in  this  composite 
widget 

XtNscreen 

Screen 

Parent's  screen 

Screen     on    which     this     widget    is 
displayed 

XtNsensitive 

Boolean 

TRUE 

Whether  widget  receives  input 

XtNtranslations 

TranslationTable 

NULL 

Event-to-action  translations 

XtNwidth 

Dimension 

Computed 
at  realize 

Width  of  form 

XtNx 

Position 

0 

x  coordinate  in  pixels 

XtNy 

Position 

0 

y  coordinate  in  pixels 

Constraints 

When  creating  children  to  be  added  to  a  Form,  the  following  additional  resources  are  retrieved 
from  the  argument  list  or  from  the  resource  database.  Note  that  these  resources  are  maintained 
by  the  Form  widget,  even  though  they  are  stored  in  the  child. 


Name 

Type 

Default 

Description 

XtNbottom 

XtEdgeType 

XtRubber 

See  text 

XtNf  romHoriz 

Widget 

NULL 

See  text 

XtNfromVert 

Widget 

NULL 

See  text 

T 

XtNhorizDi  stance 

int 

XtdefaultDi  stance 

See  text 

XtNleft 

XtEdgeType 

XtRubber 

See  text 

XtNresizable 

Boolean 

FALSE 

TRUE  if  children  allowed  to  resize 

themselves 

XtNright 

XtEdgeType 

XtRubber 

See  text 

XtNtop 

XtEdgeType 

XtRubber 

See  text 

XtNvert  Distance 

int 

XtdefaultDi  stance 

See  text 

These  resources  are  called  constraints,  and  can  be  specified  to  the  Form  to  indicate  where  the 
child  should  be  positioned  within  the  Form. 

The  resources  XtNhorizDistance  and  XtNf  romHoriz  let  the  widget  position  itself  a 
specified  number  of  pixels  horizontally  away  from  another  widget  in  the  form.  As  an  example, 
XtNhorizDistance  could  equal  10  and  XtNf  romHoriz  could  be  the  widget  ID  of 
another  widget  in  the  Form.  The  new  widget  will  be  placed  10  pixels  to  the  right  of  the  widget 
defined  in  XtNf  romHoriz.  If  XtNf  romHoriz  equals  NULL,  then  XtNhorizDistance  is 
measured  from  the  left  edge  of  the  Form. 
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Similarly,  the  resources  XtNvertDistance  and  xtNfromVert  let  the  widget  position 
itself  a  specified  number  of  pixels  vertically  away  from  another  widget  in  the  Form.  If  xt- 
Nf  romVert  equals  NULL,  then  XtNvertDistance  is  measured  from  the  top  of  the  Form. 
Form  provides  a  cvtStringToWidget  conversion  procedure.  Using  this  procedure,  the 
resource  database  may  be  used  to  specify  the  xtNf  romHoriz  and  XtNfromVert  resources 
by  widget  name  rather  than  widget  ID.  The  string  value  must  be  the  name  of  a  child  of  the 
same  Form  widget  parent 

The  xtNtop,  xtNbottom,  xtNlef  t,  and  xtNright  resources  tell  the  Form  where  to  posi 
tion  the  child  when  the  Form  is  resized.  XtEdgeType  is  defined  in  <XlllXawlForm.h>  and  is 
one  of XtChainTop, XtChainBottom,  XtChainLef t, XtChainRight, or  XtRubber. 

The  values  XtChainTop,  XtChainBottom,  XtChainLef  t,  and  XtChainRight  specify 
that  a  constant  distance  is  to  be  maintained  from  an  edge  of  the  child  to  the  top,  bottom,  left, 
and  right  edges,  respectively,  of  the  Form.  The  value  XtRubber  specifies  that  a  proportional 
distance  from  the  edge  of  the  child  to  the  left  or  top  edge  of  the  Form  is  to  be  maintained  when 
the  form  is  resized.  The  proportion  is  determined  from  the  initial  position  of  the  child  and  the 
initial  size  of  the  Form.  Form  provides  an  xtrStringtoXtrEdgeType  resource  converter 
to  allow  the  resize  constraints  to  be  specified  easily  in  a  resource  file. 

The  default  width  of  the  Form  is  the  minimum  width  needed  to  enclose  the  children  after  com 
puting  their  initial  layout,  with  a  margin  of  xtNdefaultDistance  at  the  right  and  bottom 
edges.  If  a  width  and  height  is  assigned  to  the  Form  that  is  too  small  for  the  layout,  the  children 
will  be  clipped  by  the  right  and  bottom  edges  of  the  Form. 

Programmatic  Interface 

To  create  a  Form  widget  instance,  use  xtCreateWidget  and  specify  the  class  variable 

formWidget Class. 

To  add  a  new  child  to  a  Form,  use  XtCreateWidget  and  specify  the  widget  ID  of  the 
previously  created  Form  as  the  parent  of  the  child. 

To  remove  a  child  from  a  Form,  use  xtUnmanageChild  or  xtDestroyWidget  and 
specify  the  widget  ID  of  the  child  widget. 

To  destroy  a  Form  widget  instance,  use  XtDestroyWidget  and  specify  the  widget  ID 
of  the  Form.  All  children  of  the  Form  are  destroyed  automatically  at  the  same  time. 

When  a  new  child  becomes  managed  or  an  old  child  unmanaged,  the  Form  widget  will 
recalculate  the  positions  of  its  children  according  to  the  values  of  the  xtNhoriz- 
Distance,  XtNf  romHoriz,  XtNvertDistance,  and  XtNfromVert  constraints  at 
the  time  the  change  is  made.  No  re-layout  is  performed  when  a  child  makes  a  geometry 
request. 

To  force  or  defer  a  re-layout  of  the  Form  widget,  use  XawFo  rmDo  Lay  out : 

void  XawFormDoLayout (w,    do_layout) 
Widget    w; 
Boolean    do_layout; 
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v  Specifies  the  Form  widget 

do_iayout       Enables  (if  True)  or  disables  (if  False;  layout  of  the  Form 
---,'- 

akiof  aevenri  changes  to  the  ctuldreo  of  a  Form  widget  after  the  Form  has  been 
realized,  it  is  a  good  idea  tod^atie  it4»yo«t  unuJ  all  rhaagri  lave  been  made,  tfaea  alkyw 
the  layout  The  Font  •ii%rt  in»eaae«s  an  internal  count  each  time  xtFonoDo Layout 
if  called  with  do_layout  set  to  False;  the  Form  widget  decrements  the  count  when 
do_2ayout  is  True.  Whea  At  count  reaches  0,  the  Form  widget  performs  a  re-layout 
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Grip 


NMM 

Grip  widget  —  attaci«Mat  point  for  dragging  oincr  wtc^ecs. 


Synopsis 


Xi: 


XtCr< 


Class  Hierarchy 

Core  ->  Simple  — *  Grip 

DMCriptton 

The  Gnp  widget  provides  a  small  regkw  in  which  user  input  events  \,such  as 
ButtonRelease)  may  be  handled  The  most  common  use  (tor  the  Gnp  wtdlget  is  as  an 
attachment  point  for  visually  repositioning  an  object,  such  as  the  pane  border  in  a  Faned 


Resources 

When  creating  a  Grip  widget  instance,  the  following  resources  are  retrieved  from  the  ajrgwsnt 
list  or  from  the  resource  database: 
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Name 

Type 

Default 

Description 

XtNforeground 

Pixel 

XtDefault- 
Foreground 

Window  background  color 

XtNheight 

Dimension 

8 

Height  of  the  widget 

XtNinsensltiveBorder 

Pixmap 

GreyPixmap 

Pixmap     will    be    tiled    into    the 
widget's     border     if     the     widget 
becomes  insensitive 

XtNmappedWhen- 
Managed 

Boolean 

TRUE 

Whether  XtMapWidget  is  automatic 

XtNscreen 

Screen 

Parent's  screen 

Screen    on    which    this    widget    is 
displayed 

XtNsensitive 

Boolean 

TRUE 

Whether  widget  should  receive  input 

XtNtranslations 

TranslationTable 

NULL 

Event-to-action  translations 

XtNwidth 

Dimension 

8 

Width  of  the  widget 

XtNx 

Position 

0 

x  coordinate  in  pixels 

XtNy 

Position 

0 

y  coordinate  in  pixels 

Note  that  the  Grip  widget  displays  its  region  with  the  foreground  pixel  only. 
Translations  and  Actions 

The  Grip  widget  does  not  declare  any  default  event  translation  bindings,  but  it  does  declare  a 
single  action  routine  named  GripAction  in  its  action  table.  The  client  specifies  an  arbitrary 
event  translation  table,  giving  parameters  to  the  GripAction  routine. 

The  GripAction  action  executes  the  callbacks  on  the  xtNcallback  list,  passing  as 
call_data  a  pointer  to  a  GripCallData  structure,  defined  in  <Xll/Xaw/Grip.h>: 

typedef   struct  _GripCallData    { 

XEvent    *event; 

String    *params; 

Cardinal   num_params; 
}    GripCallDataRec,    *GripCallData; 

In  this  structure,  event  is  a  pointer  to  the  input  event  that  triggered  the  action,  and  params 
and  num_params  give  the  string  parameters  specified  in  the  translation  table  for  the  particular 
event  binding. 

The  following  is  an  example  of  a  GripAction  translation  table: 

<BtnlDown> : GripAction (press) 
<BtnlMotion> : GripAction (move) 
<BtnlUp> : GripAction (release) 

Programmatic  Interface 

To  create  a  Grip  widget  instance,  use  XtCreateWidget  and  specify  the  class  variable 

gripWidget Class. 

•       To  destroy  a  Grip  button  widget  instance,  use  xtDestroyWidget  and  specify  the  ID  of 
the  Grip  widget. 
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Name 

Label  widget  —  widget  to  display  a  non-editable  string. 

Synopsis 

#include  <Xll/StringDefs . h> 

#include  <Xll/Intrinsic .h> 

#include  <Xll/Xaw/Label .h> 

widget  =  XtCreateWidget (name,  labelWidgetClass, .  .  . )  ; 

Class  Hierarchy 

Core  — >  Simple  — >  Label 

Description 

A  Label  is  an  non-editable  text  string  or  pixmap  that  is  displayed  within  a  window.  The  string 
may  contain  multiple  lines  of  Latin  1  characters.  It  can  be  aligned  to  the  left,  right,  or  center  of 
its  window.  A  Label  can  be  neither  selected  nor  directly  edited  by  the  user. 

Resources 

When  creating  a  Label  widget  instance,  the  following  resources  are  retrieved  from  the  argu 
ment  list  or  from  the  resource  database: 


Name 

Type 

Default 

Description 

XtNaccelerators 

AcceleratorTable 

NULL 

List  of  event-to-action  bindings  to  be 
executed  by  this  widget,  even  though 
the  event  occurred  in  another  widget 

XtNancestor- 
Sensitive 

Boolean 

True 

Sensitivity  state  of  the  ancestors  of  this 
widget:  a  widget  is  insensitive  if  either 
it  or  any  of  its  ancestors  is  insensitive 

XtNbackground 

Pixel 

XtDefault- 
Background 

Window  background  color 

XtNbackground- 
Pixmap 

Pixmap 

XtUnspecified- 
Pixmap 

Window  background  pixmap 

XtNbitmap 

Pixmap 

None 

Pixmap  to  display  in  place  of  the  label 

XtNborderColor 

Pixel 

XtDefault- 

Window  border  color 

Foreground 

XtNborderPixmap 

Pixmap 

XtUnspecified- 
Pixmap 

Window  border  pixmap 

XtNborderWidth 

Dimension 

1 

Border  width  in  pixels 

XtNcolormap 

Colormap 

Parent's  colormap 

Colormap  that  this  widget  will  use 

XtNcursor 

Cursor 

None 

Pointer  cursor 

XtNdepth 

int 

Parent's  depth 

Depth  of  this  widget's  window 

XtNdestroy- 
Callback 

XtCallbackList 

NULL 

Callbacks  forxtDestroyWidget 

XtNfont 

XFont  Struct* 

XtDefaultFont 

Label  font 

XtNforeground 

Pixel 

XtDefault- 
Foreground 

Foreground  color 
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Name 

Type 

Default 

Description 

XtNheight 

Dimension 

Font  height  +  2  * 

Height  of  widget 

XtNinternalHeight 

XtNinsensitive- 

Pixmap 

GrayPixmap 

Border  when  not  sensitive 

Border 

XtNinternal- 

Dimension 

2 

See  note 

Height 

XtNinternalWidth 

Dimension 

4 

See  note 

XtNjustify 

Xt  Justify 

XtJustifyCenter 

Type  of  text  alignment 

XtNlabel 

String 

Name  of  widget 

String  to  be  displayed 

XtNmappedWhen- 

Boolean 

TRUE 

Whether  XtMapWidget  is  automatic 

Managed 

XtNresize 

Boolean 

TRUE 

Whether  to  auto-resize  in  Set  Values 

XtNscreen 

Screen 

Parent's  screen 

Screen     on     which     this     widget     is 

displayed:  this  is  not  a  sellable  resource 

XtNsensitive 

Boolean 

TRUE 

Whether  widget  receives  input 

XtNtranslations 

Translation- 

See  below 

Event-to-action  translations 

Table 

XtNwidth 

Dimension 

XtNlabel  width  +2   * 

Width  of  widget 

XtNinternalWidth 

XtNx 

Position 

0 

x  coordinate  in  pixels 

XtNy 

Position 

0 

y  coordinate  in  pixels 

Note  that  the  Label  widget  supports  only  the  XtNdestroyCallback  callback  list. 
The  new  resources  associated  with  Label  are: 

XtNbitmap 

Specifies  a  bitmap  to  display  in  place  of  the  text  label.  The  bitmap  can  be  specified  as  a 
string  in  the  resource  database.  The  StringToPixmap  converter  will  interpret  the 
string  as  the  name  of  a  file  in  the  bitmap  utility  format  that  is  to  be  loaded  into  a  pixmap. 
The  string  can  be  an  absolute  or  a  relative  filename.  If  a  relative  filename  is  used,  the 
directory  specified  by  the  resource  name  bitmapFilePath  or  the  resource  class 
BitmapFilePath  is  added  to  the  beginning  of  the  specified  filename.  If  the 
bitmapFilePath  resource  is  not  defined,  the  default  directory  on  a  POSIX-based  sys 
tem  is  lusrlincludelXll  /bitmaps. 

XtNinternalHeight 

Represents  the  distance  in  pixels  between  the  top  and  bottom  of  the  label  text  or  bitmap 
and  the  horizontal  edges  of  the  Label  widget 

XtNinternalWidth 

Represents  the  distance  in  pixels  between  the  ends  of  the  label  text  or  bitmap  and  the  ver 
tical  edges  of  the  Label  widget 
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XtNjustify 

Specifies  left,  center,  or  right  alignment  of  the  label  string  within  the  Label  widget.  If  it 
is  specified  within  an  ArgList,  one  of  the  values  Xt  JustifyLef t,  Xt  Justify- 
Center,  or  Xt  JustifyRight  can  be  specified.  In  a  resource  of  type  string,  one  of 
the  values  left,  center,  or  right  can  be  specified. 

XtNlabel 

Specifies  the  text  string  that  is  to  be  displayed  in  the  button  if  no  bitmap  is  specified.  The 
default  is  the  widget  name  of  the  Label  widget 

XtNresize 

Specifies  whether  the  Label  widget  should  attempt  to  resize  to  its  preferred  dimensions 
whenever  Xt  Set  Values  is  called  for  it 

Programmatic  Interface 

•       To  create  a  Label  widget  instance,  use  xtCreateWidget  and  specify  the  class  variable 
labelWidgetClass. 

To  destroy  a  Label  widget  instance,  use  xtDestroyWidget  and  specify  the  widget  ID 
of  the  label. 
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Name 

List  widget  —  widget  for  managing  row-column  geometry. 

Synopsis 

#include  <Xll/StringDef s .h> 

tinclude  <Xll/Intrinsic.h> 

#include  <Xll/Xaw/List .h> 

widget  =  XtCreateWidget (namet  listWidgetClass, . . . ) ; 

Class  Hierarchy 

Core  — >  Simple  — >  List 

Description 

The  List  widget  is  a  rectangle  that  contains  a  list  of  strings  formatted  into  rows  and  columns. 
When  one  of  the  strings  is  selected,  it  is  highlighted,  and  an  application  callback  routine  is 
invoked.  Only  one  string  may  be  selected  at  a  time. 

Resources 

When  creating  a  List  widget  instance,  the  following  resources  are  retrieved  from  the  argument 
list  or  from  the  resource  database: 


Name 

Type 

Default 

Description 

XtNaccelerators 

Accel  e  rat  or  Table 

NULL 

List  of  event-to-action  bindings  to  be 
executed  by  this  widget,  even  though 
the  event  occurred  in  another  widget 

XtNancestor- 
Sensitive 

Boolean 

True 

Sensitivity  state  of  the  ancestors  of  this 
widget:  a  widget  is  insensitive  if  either 
it  or  any  of  its  ancestors  is  insensitive 

XtNbackground 

Pixel 

XtDefault- 
Background 

Window  background  color 

XtNbackground- 
Pixmap 

Pixmap 

XtUnspecified- 
Pixmap 

Window  background  pixrnap 

XtNborderColor 

Pixel 

XtDefault- 

Window  border  color 

Foreground 

XtNborderPixmap 

Pixmap 

XtUnspecif  ied- 
Pixmap 

Window  border  pixmap 

XtNborderWidth 

Dimension 

1 

Width  of  border 

XtNcallback 

XtCallbackList 

NULL 

Selection  callback  function 

XtNcolormap 

Colormap 

Parent's  colormap 

Colormap  that  this  widget  will  use 

XtNcolumnSpacing 

Dimension 

6 

Space  between  columns  in  the  list 

XtNcursor 

Cursor 

left_ptr 

Pointer  cursor 

XtNdefaultColumns 

int 

2 

Number  of  columns  to  use 

XtNdepth 

int 

Parent's  depth 

Depth  of  this  widget's  window 

XtNdestroy- 
Callback 

XtCallbackList 

NULL 

Callbacks  forXtDestroyWidget 

XtNfont 

XFontStruct* 

XtDefaultFont 

Font  for  list  text 
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Name 

Type 

Default 

Description 

XtNforceColumns 

Boolean 

FALSE 

Force  the  use  of  XtNdefaultColumns 

XtNforeground 

Pixel 

XtDefault- 

Foreground  (text)  color 

Foreground 

XtNheight 

Dimension 

Contains  list 

Height  of  widget 

exactly 

XtNi  risen  sit  ive- 

Pixmap 

GrayPixmap 

Border  when  not  sensitive 

Border 

XtNinternalHeight 

Dimension 

2 

Spacing  between  list  and  widget  edges 

XtNinternalWidth 

Dimension 

4 

Spacing  between  list  and  widget  edges 

XtNlist 

String   * 

Name  of  widget 

An  array  of  strings  that  is  the  list 

XtNlongest 

int 

Computed 

Length  of  the  longest  list  item 

at  realize 

in  pixels 

XtNmappedWhen- 

Boolean 

TRUE 

Whether  XtMapWidget  is  automatic 

Managed 

XtNnumberSt  rings 

int 

Number  of 

Number  of  items  in  the  list 

strings 

XtNpasteBuf  fer 

Boolean 

FALSE 

Copy  the  selected  item  to  cut  buffer  0 

XtNrowSpacing 

Dimension 

4 

Space  between  rows  in  the  list 

XtNscreen 

Screen 

Parent's  screen 

Screen     on     which     this     widget     is 

displayed 

XtNsensitive 

Boolean 

TRUE 

Whether  widget  receives  input 

XtNtranslations 

Translation- 

NULL 

Event-to-action  translations 

Table 

XtNverticalList 

Boolean 

FALSE 

Specify  the  layout  of  list  items 

XtNwidth 

Dimension 

Contains  list 

Width  of  widget 

exactly 

XtNx 

Position 

0 

x  coordinate  in  pixels 

XtNy 

Position 

0 

y  coordinate  in  pixels 

The  new  resources  associated  with  the  List  widget  are: 

XtNcallback 

All  functions  on  this  list  are  called  whenever  the  notify  action  is  invoked. 

XtNrowSpacing 
XtNcolumnSpacing 

Specify  the  amount  of  space  between  each  of  the  rows  and  columns  in  the  list. 

XtNdefaultColumns 

Specifies  the  default  number  of  columns,  which  is  used  when  neither  the  width  nor  the 
height  of  the  List  widget  is  specified  or  when  XtNforceColumns  is  True. 

XtNforceColumns 

Specifies  that  the  default  number  of  columns  is  to  be  used  no  matter  what  the  current  size 
of  the  List  widget  is. 

XtNfont 

Specifies  the  font  to  be  used  to  display  the  list. 


542 


X  Toolkit  Intrinsics  Reference  Manual 


Xt  -  Athena  Classes  (continued)  List 

XtNforeground 

Specifies  a  pixel  value  that  indexes  the  widget's  colormap  in  order  to  derive  the  color  to 
be  used  to  paint  the  text  of  the  list  elements. 

XtNinternalHeight 

Represents  a  margin,  in  pixels,  between  the  top  and  bottom  of  the  list  and  the  edges  of 
the  List  widget 

XtNinternalWidth 

Represents  a  margin,  in  pixels,  between  the  left  and  right  edges  of  the  list  and  the  edges 
of  the  List  widget 

XtNlist 

Specifies  the  array  of  text  strings  that  is  to  be  displayed  in  the  List  widget.  If  the  default 
for  XtNnumber Strings  is  used,  the  list  must  be  NULL-terminated.  If  a  value  is  not 
specified  for  the  list,  the  number  of  strings  is  set  to  1,  and  the  name  of  the  widget  is  used 
as  the  list. 

XtNlongest 

Specifies  the  length,  in  pixels,  of  the  longest  string  in  the  current  list.  If  the  client  knows 
the  length,  it  should  specify  it;  otherwise,  the  List  widget  computes  a  default  length  by 
searching  through  the  list 

XtNnumber Strings 

Specifies  the  number  of  strings  in  the  current  list  If  a  value  is  not  specified,  the  list  must 
be  NULL-terminated. 

XtNpasteBuffer 

If  this  is  True,  then  the  value  of  the  string  selected  will  be  put  into  X  cut  buffer  0. 

XtNverticalList 

If  this  is  True,  the  elements  in  the  list  are  arranged  vertically;  if  False,  the  elements 
are  arranged  horizontally. 

Translations  and  Actions 

The  List  widget  has  three  predefined  actions:  Set,  Unset,  and  Notify.  Set  and  Unset 
allow  switching  the  foreground  and  background  colors  for  the  current  list  item.  Notify 
allows  processing  application  callbacks. 

The  following  is  the  default  translation  table  used  by  the  List  widget 

<BtnlDown>, <BtnlUp> : Set ( )  Notify (  ) 

Programmatic  Interface 

•  To  create  a  List  widget  instance,  use  xtCreateWidget  and  specify  the  class  variable 
listWidgetClass. 

•  To  destroy  a  List  widget  instance,  use  XtDestroyWidget  and  specify  the  widget  ID  of 
the  List  widget 
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The  List  widget  supports  two  callback  lists: 

—  XtNdestroyCallback 

—  XtNcallback 

The  notify  action  executes  the  callbacks  on  the  the  XtNcallback  list. 

The  call_data  argument  passed  to  callbacks  on  the  XtNcallback  list  is  a  pointer  to 
an  xtListReturnStruct  structure,  defined  in  <Xll/Xaw/List.h>: 

typedef   struct  _XtListReturnStruct    { 

String   string;  /*    string   shown    in   the    list    */ 

int    index;  /*    index   of   the    item   selected    */ 

}    XtListReturnStruct; 

•       To  change  the  list  of  strings  that  is  displayed,  use: 

void  XawListChange (w,  list,  nitems,  longest,  resize) 
Widget  w; 
String  *  list; 
int  nitems,  longest; 
Boolean  resize; 

where: 

w  Specifies  the  widget  ID. 

list  Specifies  the  new  list  for  the  List  widget  to  display. 

nitems  Specifies  the  number  of  items  in  the  list.  If  a  value  less  than  1  is  speci 
fied,  the  list  must  be  NULL-terminated,  and  the  List  widget  calculates 
the  number  for  you. 

longest  Specifies  the  length  of  the  longest  item  in  the  list  in  pixels.  If  a  value 
less  than  1  is  specified,  the  List  widget  calculates  the  value  for  you. 

resize  Specifies  a  Boolean  value  that  indicates  whether  the  List  widget  should 
try  to  resize  itself  (True)  or  not  (False)  after  making  the  change. 
Note  that  the  constraints  of  the  parent  of  the  List  widget  are  always 
enforced,  regardless  of  the  value  specified. 

Note  that  XawListChange  will  Unset  all  list  elements  that  are  currently  Set  before 
the  list  is  actually  changed.  The  list  is  used  in  place,  and  it  must  remain  usable  either  for 
the  lifetime  of  the  List  widget  or  until  the  list  has  been  changed  again  with  this  function  or 
withXtSetValues. 

To  highlight  an  item  in  the  list,  use: 

void  XawListHighlight (w,  item); 
Widget  w; 
int  item; 


544  X  Toolkit  Intrinsics  Reference  Manual 


Xt  -  Athena  Classes  (continued)  List 

where: 

w  Specifies  the  widget  ID. 

item  Specifies  the  index  into  the  current  list  that  indicates  the  item  to  be 

highlighted. 

Only  one  item  can  be  highlighted  at  a  time.  If  an  item  is  already  highlighted  when  Xaw- 
ListHighlight  is  called,  the  highlighted  item  is  immediately  unhighlighted  and  the 
new  item  is  highlighted. 

•  To  unhighlight  the  currently  highlighted  item  in  the  list,  use: 

void  XawListUnhighlight (w) ; 
Widget  w; 

where  w  specifies  the  widget  ID. 

•  To  retrieve  an  item  in  the  list,  use: 

XtListReturnStruct  *XtListShowCurrent ( w) ; 
Widget  w; 

where  w  specifies  the  widget  ID. 

The  XawListShowCurrent  function  returns  a  pointer  to  an  XawListReturn- 
Struct  structure  that  contains  the  currently  highlighted  item.  If  the  value  of  the  index 
member  is  XT_LIST_NONE,  the  string  member  is  undefined,  which  indicates  that  no  item  is 
currently  selected. 
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Name 

MenuButton  widget  —  button  that  pops  up  a  menu. 


Synopsis 

tinclude 
#include 
tinclude 


<Xll/StringDef  s  .  h> 
<Xll/Intrinsic  .h> 
<Xll/Xaw/MenuButton  .h> 


widget  =  XtCreateWidget  (name,  menuButtonWidgetClass,  .  .  .  )  ; 

Class  Hierarchy 

Core  —  >  Simple  —  >  Label  —  »  Command  —  >  MenuButton 

Description 

The  MenuButton  widget  is  an  area,  often  rectangular,  that  contains  a  text  or  pixmap  label.  This 
selectable  area  is  referred  to  as  a  button.  When  the  pointer  cursor  is  on  the  button,  the  button 
border  is  highlighted  to  indicate  that  the  button  is  ready  for  selection.  When  pointer  button  1  is 
pressed,  the  MenuButton  widget  pops  up  the  menu  that  has  been  named  in  the  menuName 
resource. 


Resources 

When  creating  a  MenuButton  widget  instance,  the 
argument  list  or  from  the  resource  database: 


following  resources  are  retrieved  from  the 


Name 

Type 

Default 

Description 

XtNaccelerators 

Accel  eratorTable 

NULL 

List  of  event-to-action  bindings  to  be 
executed  by  this  widget,  even  though  the 
event  occurred  in  another  widget 

XtNancestor- 
Sensitive 

Boolean 

True 

Sensitivity  state  of  the  ancestors  of  this 
widget:  a  widget  is  insensitive  if  either  it 
or  any  of  its  ancestors  is  insensitive 

XtNbackground 

Pixel 

XtDefault- 
Background 

Window  background  color 

XtNbackground- 
Pixmap 

Pixmap 

XtUnspecified- 
Pixmap 

Window  background  pixmap 

XtNbitmap 

Pixmap 

None 

Pixmap  to  display  in  place  of  the  label 

XtNborderColor 

Pixel 

XtDefault- 

Window  border  color 

Foreground 

XtNborder  Pixmap 

Pixmap 

XtUnspecified- 
Pixmap 

Window  border  pixmap 

XtNborderWidth 

Dimension 

1 

Width  of  button  border 

XtNcallback 

XtCallbackList 

NULL 

Callback  for  button  select 

XtNcolormap 

Colormap 

Parent's  colormap 

Colormap  that  this  widget  will  use 

XtNcornerRound- 

Dimension 

25 

See  below 

Percent 

XtNcursor 

Cursor 

None 

Pointer  cursor 

XtNdepth 

int 

Parent's  depth 

Depth  of  this  widget's  window 
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Name 

Type 

Default 

Description 

XtNdestroy- 
Callback 

XtCallbackList 

NULL 

Callbacks  forXtDestroyWidget 

XtNfont 

XFontStruct 

XtDefaultFont 

Label  font 

XtNforeground 

Pixel 

XtDefault- 
Foreground 

Foreground  color 

XtNheight 

Dimension 

Font  height  +  2  * 

XtNinternalHeight 

Button  height 

XtNhighlight- 
Thickness 

Dimension 

2 

Width  of  border  to  be  highlighted 

XtNinsensitive- 

Pixmap 

GrayPixmap 

Border  when  not  sensitive 

Border 

XtNinternal- 

Dimension 

2 

Internal  border  height  for  highlighting 

Height 

XtNinternalWidth 

Dimension 

4 

Internal  border  width  for  highlighting 

XtN  justify 

Justify 

XtJustifyCenter 

Type  of  text  alignment 

XtNlabel 

String 

name  of  widget 

Button  label 

XtNmappedWhen- 
Managed 

Boolean 

True 

Whether  XtMapWidget  is  automatic 

XtNmenuName 

String 

"menu" 

Name  of  menu 

XtNresize 

Boolean 

True 

Whether  to  auto-resize  in  SetValues 

XtNscreen 

Screen 

Parent's  screen 

Screen  on  which  this  widget  is  displayed. 
This  is  not  a  sellable  resource 

XtNsensitive 

Boolean 

True 

Whether  widget  receives  input 

XtNshapeStype 

ShapeStyle 

Rectangle 

Type  of  nonrectangular  button 

XtNtranslations 

Trans  1  at  ionTable 

See  below 

Event-to-action  translations 

XtNwidth 

Dimension 

XtNlabel  width  +  2  * 

XtNinternalWidth 

XtNx 

Position 

0 

x-coordinate  in  pixels 

XtNy 

Position 

0 

y-coordinate  in  pixels 

Note  that  the  MenuButton  widget  supports  two  callback  lists:  XtNdestroyCallback  and 
xtNcallback.  The  notify  action  executes  the  callbacks  on  the  XtNcallback  list.  The 
call_data  argument  is  unused. 

The  new  resource  (not  inherited  from  superclasses)  associated  with  the  MenuButton  widget  is: 

XtNmenuName 

The  name  of  a  pop-up  shell  to  pop-up  as  a  menu.  The  MenuButton  searches  for  this 
name  using  xtNameToWidget,  starting  with  itself  as  the  reference  widget.  If  unsuc 
cessful,  MenuButton  continues  to  search  up  the  widget  tree,  using  each  of  its  ancestors  as 
the  reference  widget  If  still  unsuccessful,  MenuButton  prints  a  warning  message  and 
gives  up.  When  the  menu  is  found,  it  is  popped  up  with  an  exclusive  Xt  grab  mode  and 
with  a  global  passive  grab  of  the  pointer  button  that  was  pressed. 
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Translations  and  Actions 

The  following  default  translation  bindings  are  used  by  the  MenuButton  widget: 

<EnterWindow>: highlight ( ) 
<LeaveWindow> : reset ( ) 
<BtnDown> : reset ( )    PopupMenu ( ) 

With  these  bindings,  the  user  can  cancel  the  action  before  releasing  the  button  by  moving  the 
pointer  out  of  the  MenuButton  widget 

The  MenuButton  widget  supports  the  following  actions: 

Switching  the  button  between  the  foreground  and  background  colors  with  set  and 

unset. 

Processing  application  callbacks  with  notify. 

•  Switching  the  internal  border  between  highlighted  and  unhighlighted  states  with  high 
light  and  unhighlight. 

•  Popping  up  a  menu  with  PopupMenu. 

The  actions  supported  by  MenuButton  are  listed  below: 

highlight(condi  ti  on) 

Displays  the  internal  highlight  border  in  the  color  (xtNf  oreground  or 
XtNbackground)  that  contrasts  with  the  interior  color  of  the  Menu- 
Button  widget  The  conditions  WhenUnset  and  Always  are  understood 
by  this  action  procedure.  If  no  argument  is  passed,  WhenUnset  is 
assumed. 


unhighlight  () 

set() 

unsetQ 

resetQ 

notify() 


Displays  the  internal  highlight  border  in  the  color  (XtNf  oreground  or 
XtNbackground)  that  matches  the  interior  color  of  the  MenuButton 
widget 

Enters  the  set  state,  in  which  notify  is  possible,  and  displays  the  interior 
of  the  button,  including  the  highlight  border,  in  the  foreground  color.  The 
label  or  pixmap  is  displayed  in  the  background  color. 

Cancels  the  set  state  and  displays  the  interior  of  the  button,  including  the 
highlight  border,  in  the  background  color.  The  label  or  pixmap  is 
displayed  in  the  foreground  color. 

Cancels  any  set  or  highlight  action  and  displays  the  interior  of  the 
button  in  the  background  color,  with  the  label  or  pixmap  displayed  in  the 
foreground  color. 

Executes  the  callback  list  specified  by  xtNcallback,  if  executed  in  the 
set  state.  The  value  of  the  call_da  t  a  argument  is  undefined. 


PopupMenuQ          Pops  up  the  menu  specified  by  the  xtNmenuName  resource. 
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Programmatic  interface 

To  create  a  MenuButton  widget  instance,  use  XtCreateWidget  and  specify  the  class 
variable  menuButtonWidgetClass. 

•       To  destroy  a  MenuButton  widget  instance,  use  xtDestroyWidget  and  specify  the 
widget  ID  of  the  MenuButton  widget 

See  Also 

Command(5),  Label(5),  SimpleMenu(5). 
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Name 

I'aned  widget  —  geometry-managing  widgel  for  veiiual  01  hon/onlal  tiles. 


Synopsis 

K  Lnc  lu.i^  <X13    Sti  iiuiivt  -..!,- 

» Include  <XU    tnti  Ln»ic.h> 

»  hu-Uuirt  vXl  1  /Xdw/ Pctntni.h  • 

:\/et  ;  X 


Class  Hierarchy 
Core  ->  Composite 


Constraint  — >  Paned 


Description 

'IV  railed  widget  manages  children  in  .1  \eitu  ally  01  hori/ontally  tiled  fashion.  I'hc  panes 
may  be  dynamically  rest/.eil  by  tlie  user  by  using  the  x"/'v  {^M  apivai  neai  the  light  01  lx>tloni 
e<lge  of  the  K>ivler  between  two  iwnes. 

When  tlie  |H>intei  is  (nvsitiiMied  on  a  gup  and  piessed,  an  arrow  is  displayeil  tluit  nuluales  the 
pane  that  is  being  resi/ed.  While  keeping  the  |H»intei  button  down,  the  usei  can  move  the 
pointer  up  and  ilown  (or  left  and  right).  This,  in  turn,  changes  the  border  between  the  panes, 
causing  one  pane  to  shrink  and  some  olhei  pane  ^01  panes)  to  giow.  The  si/e  ot  the  I'ancd 
wiilget  will  not  change 

The  choice  of  alternate  pane  is  a  function  of  the  xt  Nmin,  xtNnu-ix,  and  xt  N.-A  ipAvl  uust 
constraints  on  the  other  panes.  With  the  default  bindings,  button  I  resi/es  the  pane  aK>ve  01  u> 
the  left  of  the  selected  grip,  button  .*  resi/es  the  pane  tvlow  i>i  u>  the  nght  ot  tl»e  seU\  u\l  grip. 
and  button  2  rc|X>sitions  the  bordci  Ivt \\een  i\\\>  panes  only. 

Resources 

When  creating  a  Paned  widget  instance,  the  following  resources  aie  iciuocd  tu>m  ihe 
inent  list  i>r  from  ilk*  resource  database 


Nmuc 


Sena  1  1  ive 


\l  Ntvi>  Aji  omul 

e  I  Km«p 


I'Uel 


Def«uh 


HUU 


f  I  Ud 


IV>>  iiplu-n 


is-  »•  \sviiicU  by  ihw  «uij;«-i. 


>uic  ot  the  Aiu'oioiN.  »'i 
llm   \\uljii-l     i  wulgi-l   i%   U\M-H\UI\V- 

it    Cllhci    ll   »>l    »H\    i»t    U\    4IUV\KMN    IX 

u\aeiutuve 


NVuulow  tvivkjjivHin.l  pi\m*p 


tOI 

between  two  }>anoi 
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Name 

Type 

Default 

Description 

Xt  NborderColor 

Pixel 

XI  Default 

Wtlldou  ls.ul,-i  .»K>i 

Kot  t%j  i  .•iiii.l 

XtNborderPixmap 

liWMp 

XtUnapecified- 
Plxmap 

Window  border  ptunup 

XtNborderWUlt  h 

Dimension 

1 

lioivlrr  width  (pixels) 

xi  N>  -M  Idren 

Widget  U»t 

NULL 

list  of  nil  this  composite  widget's 
current  children 

XtNcolormap 

Colormap 

Parent  'i  colonnup 

Colonnap  that  this  widget  will  use 

XtNcuraor 

Curaor 

Mont 

linage  thai  will  be  displayed  as  the 
pointer  cursor  whenever  it  is  in  this 
widget,  but  not  in  any  of  its  chiUlirn 
(children  may  also  tnheiil  this  cur 
tor) 

Xt  Ndepth 

Int 

I'.uv  in'-,  depth 

Depth  of  this  widget's  window 

XtNdestroy- 
CaUback 

XtCalll.d.-U.lM 

NULL 

Callback*  forxt  Deat  .  royWliKj.-i 

XtNgrlpCursor 

1    III    -,,M 

Depends  on  urtenution 

(^irst)r  for  grip  when  not  active 

XtNgrlpIndent 

Position 

10 

Offset  of  grip  hoin  inaigin  (pixels) 

XtNgrip- 
Tranalat  Ions 

I'l  dM.-i  lat   l.Mi'l'al'lts 

Sec  below 

1  inn.  .11  bindings  tor  grip 

XtNheight 

Dlmenalon 

Depends  im  ortenuiioit 

Height  of  Pane 

XtNhoriiontal- 

BetweenCut  aor 

Curaor 

ab_up  arrow 

t  m  -.,.i  to  be  used  for  the  grip  when 
changing    the    boundary    between 

two  panes 

XtNhorizontal- 
GripCuraor 

I    U  1    ',  .  •  1 

st>   d  (iouble   arrow 

Curior   to   be   used   for  the   gups 
when  they  are  not  active 

XtNinternal 
BorderColor 

Pixel 

XtDefaultforegi  >MHU! 

Internal  boidei  coloi  ol  the  wi.l^i-i\ 
window 

XtNinternal- 
BorderWldt  h 

Pllllfll-i  I.  Ml 

1 

Amount  of  space  lefl  between  panes 

XtNleftCuraor 

Curaor 

uk>    left    arrow 

Cunor  for  residing  the  pane  to  tin- 
left  of  the  gri|> 

XtNlowerCuraor 

Curaor 

ab  down  arrow 

(\irsor  for  resi/jng  the  pane  U-l»\\ 
the  grip 

Xt  NmappedWhen 
Managed 

Boolean 

TRUE 

Whether  Xi  M  M.w  i  ,i.j.-i   is  ault>mt«iit 

XtNnumChlliit.-n 

'  .<  i  ,11  nal 

o 

Hi.  number  of  children  in  tin  .  .  "in 

posite  widget 

XtNorlentation 

Or  lent  at  Ion 

XtOrientVertlcal 

Orientation  to  slack  the  panes:  this 
value  can   be  either  Xtih 

v.-i  i  i  ,  .,  i        or       xi  Ol  ifiii 

lUu  i  .-..iii  .1  1 

XtNteflgureMode 

Boolean 

TRUE 

Whether  Pane  should  adjust  chil 
dren 

Xt  Nt  IghtCursor 

Curaor 

ab  right  arrow 

Curior  for  residing  the  pane  to  ihr 

i  if.  IH  of  the  grip 
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Name 

Type 

Default 

Description 

XtNscreen 

Screen 

Parent's  screen 

Screen   on    which   this    widget   is 
displayed 

XtNsensitive 

Boolean 

TRUE 

Whether  widget  receives  input 

XtNtranslations 

TranslationTable 

NULL 

Event-to-action  translations 

XtNupperCursor 

Cursor 

sb  up  arrow 

Cursor  for  resizing  the  pane  above 
the  grip 

XtNvertical- 
BetweenCursor 

Cursor 

sb  left   arrow 

Cursor  to  be  used  for  the  grip  when 
changing    the    boundary    between 

two  panes 

XtNvertical- 
GripCursor 

Cursor 

sb  v  double  arrow 

Cursor  to  be  used  for  the  grips 
when  they  are  not  active 

XtNwidth 

Dimension 

Depends  on  orientation 

Width  of  Pane 

XtNx 

Position 

0 

x  coordinate  in  pixels 

XtNy 

Position 

0 

y  coordinate  in  pixels 

Constraints 

During  the  creation  of  a  child  pane,  the  following  resources,  by  which  the  Paned  widget  con 
trols  the  placement  of  the  child,  can  be  specified  in  the  argument  list  or  retrieved  from  the 
resource  database: 


Name 

Type 

Default 

Description 

XtNallowResize 

Boolean 

FALSE 

If  FALSE,  ignore  child  resize  requests 

XtNmax 

Dimension 

Unlimited 

Maximum  height  for  pane 

XtNmin 

Dimension 

1 

Minimum  height  for  pane 

XtNpreferredPaneSize 

Dimension 

ask  child 

Preferred  size  of  pane                ,-  ' 

XtNresizeToPref  erred 

Boolean 

False 

Specifies  whether  to  resize  each  pane  to  its  pre 
ferred  size  when  the  Paned  widget  is  resized 

XtNshowGrip 

Boolean 

True 

Specifies  whether  to  show  a  grip  for  this  pane 

XtNskipAdjust 

Boolean 

FALSE 

TRUE  if  the  Paned  widget  should  not  automati 
cally  resize  pane 

Layout  Semantics 

To  make  effective  use  of  the  Paned  widget,  it  is  helpful  to  know  the  rules  it  uses  to  determine 
which  child  will  be  resized  in  any  given  situation.  Three  rules  determine  which  child  is 
resized.  Although  these  rules  are  always  the  same,  the  panes  that  are  searched  can  change 
depending  upon  what  caused  the  relayout. 

1 .  Do  not  let  a  pane  grow  larger  than  its  max  or  smaller  than  its  min. 

2.  Do  not  adjust  panes  with  skipAd  just  set 
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3.    Do  not  adjust  panes  away  from  their  preferred  size,  although  moving  one  closer  to  its  pre 
ferred  size  is  fine. 

When  searching  the  children,  the  Paned  widget  looks  for  panes  that  satisfy  all  three  rules;  if 
unsuccessful,  the  Paned  widget  eliminates  rule  3  and  then  rule  2.  Rule  1  is  always  enforced. 

If  the  relayout  is  due  to  a  resize  or  a  change  in  management,  then  the  panes  are  searched  from 
bottom  to  top.  If  the  relayout  is  due  to  grip  movement,  then  they  are  searched  from  the  grip 
selected  in  the  direction  opposite  the  pane  selected. 

Resizing  Panes  from  a  Grip  Action 

The  pane  above  (or  to  the  left  of)  the  grip  is  resized  by  invoking  the  GripAction  with  Up- 
Lef  tPane  specified.  The  panes  below  (or  to  the  right  of)  the  grip  are  each  checked  against  all 
rules,  then  against  rules  2  and  1,  and  finally  against  rule  1  only.  No  pane  above  (or  to  the  left 
of)  the  chosen  pane  will  ever  be  resized. 

The  pane  below  (or  to  the  right  of)  the  grip  is  resized  by  invoking  the  GripAction  with 
LowRightPane  specified.  The  panes  above  (or  to  the  left  of)  the  grip  are  each  checked  in 
this  case.  No  pane  below  (or  to  the  right  of)  the  chosen  pane  will  ever  be  resized. 

Invoking  GripAction  with  ThisBorderOnly  specified  just  moves  the  border  between  the 
panes.  No  other  panes  are  ever  resized. 

Resizing  Panes  after  the  Paned  Widget  is  Resized 

When  the  Paned  widget  is  resized,  it  must  determine  a  new  size  for  each  pane.  There  are  two 
methods  of  doing  this.  The  Paned  widget  can  either  give  each  pane  its  preferred  size  and  then 
resize  the  panes  to  fit,  or  it  can  use  the  current  sizes  and  then  resize  the  panes  to  fit.  The 
resizeToPreferred  resource  allows  the  application  to  tell  the  Paned  widget  whether  to 
query  the  child  about  its  preferred  size  (subject  to  the  preferredPaneSize)  or  to  use  the 
current  size  when  refiguring  the  pane  locations  after  the  pane  has  been  resized. 

There  is  one  special  case.  All  panes  assume  they  should  resize  to  their  preferred  size  until  the 
Paned  widget  becomes  visible  to  the  user. 

The  Paned  widget  always  resizes  its  children  to  their  preferred  sizes  when  a  new  child  is  man 
aged,  or  a  geometry  management  request  is  honored.  The  Paned  widget  will  first  attempt  to 
resize  itself  to  contain  its  panes  exactly.  If  this  is  not  possible,  it  will  hunt  through  the  children, 
from  bottom  to  top  (right  to  left),  looking  for  a  pane  to  resize. 

Note  that  when  a  user  resizes  a  pane  with  the  grips,  the  Paned  widget  assumes  that  this  new  size 
is  the  preferred  size  of  the  pane. 

Translations  and  Actions 

The  Paned  widget  has  no  action  routines  of  its  own,  as  all  actions  are  handled  through  the  grips. 
The  grips  are  each  assigned  a  default  Translation  table. 

<BtnlDown>: GripAction (Start,  UpLeftPane) 
<Btn2Down>: GripAction (Start,  ThisBorderOnly) 
<Btn3Down>: GripAction (Start,  LowRightPane) 
<BtnlMotion>: GripAction (Move,  UpLeftPane) 
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<Btn2Motion>:GripAction (Move,  ThisBorderOnly) 
<Btn3Motion>  rGripAction (Move,  LowRightPane) 
Any<BtnUp>:GripAction (Commit) 

The  Paned  widget  interprets  the  GripAction  as  taking  two  arguments.  The  first  argument 
may  be  any  of  the  following: 

Start  Sets  up  the  Paned  widget  for  resizing  and  changes  the  cursor  of  the  grip.  The 

second  argument  determines  which  pane  will  be  resized,  and  can  take  on  any 
of  the  three  values  shown  above  (UpLeftPane,  ThisBorderOnly,  Low 
RightPane). 

Move  The  internal  borders  are  drawn  over  the  current  pane  locations  to  animate 

where  the  borders  would  actually  be  placed  if  you  were  to  move  this  border 
as  shown.  The  second  argument  must  match  the  second  argument  that  was 
passed  to  the  Start  action  that  began  this  process.  If  these  arguments  are 
not  passed,  the  behavior  is  undefined. 

Commit  This  argument  causes  the  Paned  widget  to  commit  the  changes  selected  by 

the  previously  started  action.  The  cursor  is  changed  back  to  the  grip's  inac 
tive  cursor.  No  second  argument  is  needed  in  this  case. 

Programmatic  Interface 

•  To  create  a  Paned  widget  instance,  use  xtCreateWidget  and  specify  the  class  variable 

PanedWidgetClass. 

Once  the  parent  frame  is  created,  you  then  add  panes  to  it.  Any  type  of  widget  can  be 
paned  except  Grip.  Grip  widgets  have  a  special  meaning  for  the  Paned  widget,  and  adding 
a  Grip  as  its  own  pane  will  confuse  the  Paned  widget. 

To  add  a  child  pane  to  a  Paned  frame,  use  XtCreateWidget  and  specify  the  widget  ID 
of  the  Paned  widget  as  the  parent  of  each  new  child  pane. 

•  To  delete  a  pane  from  a  paned  window  frame,  use  XtUnmanageWidget  or  xt- 
DestroyWidget  and  specify  the  widget  ID  of  the  child  pane. 

•  To  enable  or  disable  a  child's  request  for  pane  resizing,  use  XawPanedAllowResize: 

void   XawPanedAllowResize (w,    allow_resize) 
Widget    w; 
Boolean   allow_resize; 

where: 

w  Specifies  the  widget  ID  of  the  child  widget  pane. 

all ow_resi  ze      Enables  or  disables  a  pane  window  for  resizing  requests. 

If  allow_resize  is  True,  the  Paned  widget  allows  geometry  requests  from  the  child  to 
change  the  pane's  height  If  allov_resize  is  False,  the  Paned  widget  ignores  geom 
etry  requests  from  the  child  to  change  the  pane's  height.  The  default  state  is  True  before 
the  Paned  widget  is  realized  and  False  after  it  is  realized.  This  procedure  is  equivalent 
to  changing  the  XtNallowResize  resource  for  the  child. 
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•  To  change  the  minimum  and  maximum  height  settings  for  a  pane,  use  XawPanedSet- 
MinMax: 

void   XawPanedSetMinMax ( wr    min,    max) 
Widget    w; 
int   min,    max; 

where: 

w  Specifies  the  widget  ID  of  the  child  widget  pane. 

min  Specifies  the  minimum  height  of  the  child,  in  pixels. 

max  Specifies  the  maximum  height  of  the  child,  in  pixels. 

This  procedure  is  equivalent  to  setting  the  xtNmin  and  xtNmax  resources  for  the  child. 

To  retrieve  the  minimum  and  maximum  height  settings  for  a  pane,  use  XawPanedGet- 
MinMax: 

void   XawPanedGetMinMax (w,    min_return,    max_return) 
Widget    w; 
int    *min_return,     *max_return;         /*    RETURNED    */ 

where: 

w  Specifies  the  widget  ID  of  the  Paned  widget. 

m±n_re t  urn  Returns  the  minimum  height  of  the  child,  expressed  in  pixels. 

max_re  t  urn  Returns  the  maximum  height  of  the  child,  expressed  in  pixels. 

This  procedure  is  equivalent  to  getting   the  min  and  max 
resources  for  this  child. 

•  To  enable  or  disable  automatic  recalculation  of  pane  sizes  and  positions,  use  XawPaned- 
SetRef igureMode: 

void   XawPanedSetRef igureMode (w,    mode) 
Widget    w; 
Boolean   mode; 

where: 

w  Specifies  the  widget  ID  of  the  Paned  widget, 

mode  Enables  or  disables  refiguration. 

You  should  set  the  mode  to  False  if  you  add  multiple  panes  to  or  remove  multiple  panes 
from  the  parent  frame  after  it  has  been  realized,  unless  you  can  arrange  to  manage  all  the 
panes  at  once  using  xtManageChildren.  After  all  the  panes  are  added,  set  the  mode  to 
True.  This  avoids  unnecessary  geometry  calculations  and  "window  dancing." 

•  To  retrieve  the  number  of  panes  in  a  paned  widget,  use  XawPanedGetNumSub: 

int  XawPanedGetNumSub (w) 
Widget  w; 

where  w  specifies  the  widget  ID  of  the  Paned  widget 
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This  function  returns  the  number  of  panes  in  the  Paned  widget  This  is  not  the  same  as  the 
number  of  children,  since  the  grips  are  also  children  of  the  Paned  widget. 

To  delete  an  entire  Paned  widget  and  all  associated  data  structures,  use  xtDes troy- 
widget  and  specify  the  widget  ID  of  the  Paned  widget.  All  the  children  of  the  Paned 
widget  are  destroyed  automatically  at  the  same  time. 


556  X  Toolkit  Intrinsics  Reference  Manual 


-Xt-Athenadasse, '  Scrollbar 

Name 

Scrollbar  widget  —  widget  to  control  scrolling  of  viewing  area  in  another  widget. 

Synopsis 

tfinclude  <Xll/StringDefs .h> 

#include  <Xll/Intrinsic .h> 

#include  <Xll/Xaw/Scrollbar .h> 

widget  =  XtCreateWidget (name,  scrollbarWidgetClass, . . . ) ; 

Class  Hierarchy 

Core  — >  Simple  -»  Scrollbar 

Description 

The  Scrollbar  widget  is  a  rectangular  area  that  contains  a  slide  region  and  a  thumb  (slide  bar). 
A  Scrollbar  can  be  used  alone,  as  a  valuator,  or  within  a  composite  widget  (for  example,  a 
Viewport).  A  Scrollbar  can  be  aligned  either  vertically  or  horizontally. 

When  a  Scrollbar  is  created,  it  is  drawn  with  the  thumb  in  a  contrasting  color.  The  thumb  is 
normally  used  to  scroll  client  data  and  to  give  visual  feedback  on  the  percentage  of  the  client 
data  that  is  visible. 

Each  pointer  button  invokes  a  specific  scrollbar  action.  That  is,  given  either  a  vertical  or  hori 
zontal  alignment,  the  pointer  button  actions  will  scroll  or  return  data  as  appropriate  for  that 
alignment.  Pointer  buttons  1  and  3  do  not  perform  scrolling  operations  by  default.  Instead, 
they  return  the  pixel  position  of  the  cursor  on  the  scroll  region.  When  pointer  button  2  is 
clicked,  the  thumb  moves  to  the  current  pointer  position.  When  pointer  button  2  is  held  down 
and  the  pointer  is  moved,  the  thumb  follows  the  pointer. 

The  pointer  cursor  in  the  scroll  region  changes,  depending  on  the  current  action.  When  no 
pointer  button  is  pressed,  the  pointer  cursor  appears  as  an  arrow  that  points  in  the  direction(s)  in 
which  scrolling  can  occur.  When  pointer  button  1  or  3  is  pressed,  the  pointer  cursor  appears  as 
a  single-headed  arrow  that  points  in  the  logical  direction  that  the  client  will  move  the  data. 
When  pointer  button  2  is  pressed,  the  pointer  cursor  appears  as  an  arrow  that  points  to  the 
thumb. 

While  scrolling  is  in  progress,  the  application  receives  notification  from  callback  procedures. 
For  both  scrolling  actions,  the  callback  returns  the  Scrollbar  widget  ID,  client_data,  and 
the  pixel  position  of  the  pointer  when  the  button  was  released.  For  smooth  scrolling,  the  call 
back  routine  returns  the  scroll  bar  widget,  client_data,  and  the  current  relative  position  of 
the  thumb.  When  the  thumb  is  moved  using  pointer  button  2,  the  callback  procedure  is  invoked 
continuously.  When  either  button  1  or  button  3  is  pressed,  the  callback  procedure  is  invoked 
only  when  the  button  is  released,  and  the  client  callback  procedure  is  responsible  for  moving 
the  thumb. 

Resources 

When  creating  a  Scrollbar  widget  instance,  the  following  resources  are  retrieved  from  the  argu 
ment  list  or  from  the  resource  database: 
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Name 

Type 

Default 

Ascription 

XtNaccelerators 

AcceleratorTable 

NULL 

^ist  of  event-to-action  bindings  to 

be  executed  by  this  widget,  even 

hough    the    event    occurred    in 

another  widget 

XtNances  tor- 

Boolean 

True 

Sensitivity  state  of  the  ancestors 

Sensitive 

of  this  widget:  a  widget  is  insensi 

tive  if  either  it  or  any  of  its  ances 

tors  is  insensitive 

XtNbackground 

Pixel 

XtDefault- 

Window  background  color 

Background 

XtNbackground- 

Pixmap 

XtUnspecif  ied- 

Window  background  pixmap 

Pixmap 

Pixmap 

XtNborderColor 

Pixel 

XtDefault- 

Window  border  color 

Foreground 

XtNborderPixmap 

Pixmap 

XtUnspecif  ied- 

Window  border  pixmap 

Pixmap 

XtNborderWidth 

Dimension 

1 

Width  of  button  border 

XtNcolormap 

Colormap 

Parent's  colormap 

Colormap  that  this  widget  will  use 

XtNdepth 

int 

Parent's  depth 

Depth  of  this  widget's  window 

XtNdestroy- 

XtCallbackList 

NULL 

Callbacks  forXtDestroyWidget 

Callback 

XtNforeground 

Pixel 

XtDefault- 

Thumb  color 

Foreground 

XtNheight 

Dimension 

See  below 

Height  of  scroll  bar 

XtN  jumpProc 

XtCallbackList 

NULL 

Callback  for  thumb  select 

XtNlength 

Dimension 

1 

Major  dimension  (height  of 

XtorientVertical) 

XtNmappedWhen- 

Boolean 

TRUE 

Whether  xtMapWidget  is  auto 

Managed 

matic 

XtNminimumThumb 

Dimension 

7 

Smallest  size,  in  pixels,  to  which 

the  thumb  can  shrink 

XtNorientation 

XtOrientation 

Xt  Orient  Vertical 

Orientation  (vertical  or  horizon 

tal) 

XtNscreen 

Screen 

Parent's  screen 

Screen  on  which  this  widget  is 

displayed 

XtNscrollDCursor 

Cursor 

XC    sb  down_arrow 

Cursor  for  scrolling  down 

XtNscrollHCursor 

Cursor 

XC    sb  h_double_ 

Idle  horizontal  cursor 

arrow 

XtNscrollLCursor 

Cursor 

XC    sb_left_arrow 

Cursor  for  scrolling  left 

XtNscrollProc 

XtCallbackList 

NULL 

Callback  for  the  slide  region 

XtNscrollRCursor 

Cursor 

XC_sb_right_arrow 

Cursor  for  scrolling  right 

XtNscrollUCursor 

Cursor 

XC_sb_up_arrow 

Cursor  for  scrolling  up 

XtNscrollVCursor 

Cursor 

XC    sb_v_arrow_ 

Idle  vertical  cursor 

XtNsensitive 

Boolean 

TRUE 

Whether  widget  receives  input 

XtNshown 

float 

0.0 

Percentage  the  thumb  covers 
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Name 

Type 

Default 

Description 

XtNthickness 

Dimension 

14 

Minor  dimension  (height  if 

Xt  orient  Horizontal) 

XtNthumb 

Pixmap 

GrayPixmap 

Thumb  pixmap 

XtNtopOfThumb 

float 

0.0 

Position  on  scroll  bar 

XtNtranslations 

Translation- 

See  below 

Event-to-action  translations 

Table 

XtNwidth 

Dimension 

Depends  on  orientation 

Width  of  scroll  bar 

XtNx 

Position 

NULL 

x  coordinate  in  pixels 

XtNy 

Position 

NULL 

y  coordinate  in  pixels 

The  class  for  all  cursor  resources  is  xtCCursor. 

You  can  set  the  dimensions  of  the  Scrollbar  two  ways.  As  for  all  widgets,  you  can  use  the  xt  - 
Nwidth  and  xtNheight  resources.  In  addition,  you  can  use  an  alternative  method  that  is 
independent  of  the  vertical  or  horizontal  orientation: 

xtN length  Specifies  the  height  for  a  vertical  Scrollbar  and  the  width  for  a  horizontal 

Scrollbar. 

XtNthickness         Specifies  the  width  for  a  vertical  Scrollbar  and  the  height  for  a  horizontal 
Scrollbar. 

Translations  and  Actions 

The  actions  supported  by  the  Scrollbar  widget  are: 

Start  Scroll(value) 

The  possible  values  are  Forward,  Backward,  or  Continuous.  This 
must  be  the  first  action  to  begin  a  new  movement. 

NotifyScroll(value) 

The  possible  values  are  Proportional  or  FullLength.  If  the  argu 
ment  to  StartScroll  was  Forward  or  Backward,  Notif  yScroll 
executes  the  xtNscrollProc  callbacks  and  passes  either  the  position 
of  the  pointer  if  its  argument  is  Proportional  or  the  full  length  of  the 
scroll  bar  if  its  argument  is  FullLength.  If  the  argument  to  Start- 
Scroll  was  Continuous,  Notif  yScroll  returns  without  executing 
any  callbacks. 

This  must  be  the  last  action  after  a  movement  is  complete. 
Repositions  the  scroll  bar  thumb  to  the  current  pointer  location. 

Calls  the  xtNjumpProc  callbacks  and  passes  the  relative  position  of  the 
pointer  as  a  percentage  of  the  scroll  bar  length. 

The  default  bindings  for  Scrollbar  are: 


EndScrollQ 
MoveThumbQ 
NotifyThumbQ 


<BtnlDown> : StartScroll (Forward) 

<Btn2Down>: StartScroll (Continuous)  MoveThumb (  )  NotifyThumb (  ) 

<Btn3Down> : StartScroll (Backward) 
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<Btn2Motion>:MoveThumb( )    NotifyThumb ( ) 
<BtnUp>: Motif yScroll (Proportional)    EndScroll (  ) 

Examples  of  additional  bindings  a  user  might  wish  to  specify  in  a  resource  file  are: 

*Scrollbar .Translations :  \ 

~Meta<KeyPress>space : StartScroll (Forward)  Notif yScroll (FullLength)  \ 
Meta<KeyPress>space : StartScroll (Backward)  Notif yScroll (FullLength)  N 
EndScroll (  ) 

Programmatic  Interface 

•  To  create  a  Scrollbar  widget  instance,  use  xtCreateWidget  and  specify  the  class  vari 
able  scrollbarWidgetClass. 

•  To  destroy  a  Scrollbar  widget  instance,  use  XtDestroyWidget  and  specify  the  widget 
ID  for  the  Scrollbar. 

•  The  xtNscrollProc   callback  is  used  for  incremental  scrolling  and  is  called  by  the 
Notif  yScroll  action.  XtNscrollProc  looks  like  this: 

void   ScrollProc (scrollbar,    client_data,    position) 
Widget    scrollbar; 
XtPointer    client_data; 
XtPointer  position;  /*    int    */ 

where: 

scrollbar  Specifies  the  ID  of  the  Scrollbar. 

client_data  Specifies  the  client  data. 

position  Returns  the  pixel  position  of  the  thumb  in  integer 'form. 

position  is  a  signed  quantity  and  should  be  cast  to  an  int  when  used.  Using  the 
default  button  bindings,  button  1  returns  a  positive  value  and  button  3  returns  a  negative 
value.  In  both  cases,  the  magnitude  of  the  value  is  the  distance  of  the  pointer  in  pixels 
from  the  top  (or  left)  of  the  Scrollbar.  The  value  will  never  be  greater  than  the  length  of 
the  Scrollbar. 

The  xtNjumpProc  callback  is  used  for  jump  scrolling  and  is  called  by  the  Notify 
Thumb  action.  The  XtNjumpProc  callback  procedure  looks  like  this: 

void   JumpProc (scrol Ibar,    client_data,    percent) 
Widget   scrollbar; 
XtPointer   client_data; 
XtPointer  percent_ptr;  /*    float*    */ 

where: 

scrollbar       Specifies  the  ID  of  the  scroll  bar  window. 

client_data  Specifies  the  client  data. 

percent_ptr  Specifies  the  floating  point  position  of  the  thumb  (0.0  -  1.0). 
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The  XtNjumpProc  callback  is  used  to  implement  smooth  scrolling  and  is  called  by  the 
Not  if  y  Thumb  action.  percent_ptr  must  be  cast  to  a  pointer  to  float  before  use: 

float   percent   =    * (float*) percent_ptr; 

With  the  default  button  bindings,  button  2  moves  the  thumb  interactively,  and  the  Xt 
NjumpProc  is  called  on  each  new  position  of  the  pointer,  while  the  pointer  button 
remains  down.  The  value  specified  by  percent_ptr  is  the  current  location  of  the  thumb 
(from  the  top  or  left  of  the  Scrollbar)  expressed  as  a  percentage  of  the  length  of  the 
Scrollbar. 

An  older  interface  used  XtNthumbProc  and  passed  the  percentage  by  value  rather  than 
by  reference.  This  interface  is  not  portable  across  machine  architectures;  therefore,  it  is  no 
longer  supported.  This  interface  is  still  implemented  for  those  (nonportable)  applications 
that  used  it 

To  set  the  position  and  length  of  a  Scrollbar  thumb,  use  XawScrollbarSet  Thumb: 

void   XawScrollbarSetThumb { w,    top,    shown) 
Widget    w, 
float    top; 
float    shown; 

where: 

w  Specifies  the  Scrollbar  widget  ID. 

top  Specifies  the  position  of  the  top  of  the  thumb  as  a  fraction  of  the  length 

of  the  Scrollbar. 

shown  Specifies  the  length  of  the  thumb  as  a  fraction  of  the  total  length  of  the 

Scrollbar. 

XawScrollbarThumb  moves  the  visible  thumb  to  position  (0.0  -  1.0)  and  length  (0.0  - 
1.0).  Either  top  or  shown  can  be  specified  as  -1.0,  in  which  case  the  current  value  is  left 
unchanged.  Values  greater  than  1.0  are  truncated  to  1.0. 

If  called  from  XtNjumpProc,  XawScrollbarSetThumb  has  no  effect. 

Setting  Float  Resoures 

The  xtNshown  and  XtNtopOf  Thumb  resources  are  of  type  float.  These  resources  can  be 
difficult  to  get  into  an  argument  list.  The  reason  is  that  C  performs  an  automatic  cast  of  the 
float  value  to  an  integer  value,  usually  truncating  the  important  information.  The  following 
code  fragment  is  one  portable  method  of  getting  a  float  into  an  argument  list. 

top  =   0.5; 

if  (sizeof (float)  >  sizeof (XtArgVal) )  { 

/* 

*  If  a  float  is  larger  than  an  XtArgVal  then  pass  this 

*  resource  value  by  reference. 
*/ 

XtSetArg(args[0] ,  XtNshown,  Stop) ; 
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else 
/* 

T  Convince  C  not  to  perform  an  automat-'-  '-'--version, 

'  would  truncate  B . 5  -.  --  '. 

*/ 
XtArgVal  *  l_top  =  (XtArgVal  *)  ttop; 

.SetArgCargsIO],  XtNshovn,  *l_top); 
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Name 

Class  Type 

Default 

Description 

XtNcreatePopup- 

ChildProc 

Function 

NULL 

Procedure  to  call  after  the  menu 

pops  up 

XtNcolormap 

Colormap 

Parent's  colormap 

Colormap  that  this  widget  will 

use 

XtNcursor 

Cursor 

None 

Pointer  cursor 

XtNdepth 

int 

Parent's  depth 

Depth  of  this  widget's  window 

XtNdestroy- 

XtCallbackList 

NULL 

Callbacks  forXtDestroyWidget 

Callback 

XtNgeometry 

String 

NULL 

Geometry  specification  for  menu 

XtNheight 

Dimension 

Enough    space    for    all 

Menu  height 

entries 

XtNlabel 

String 

name  of  widget 

See  below 

XtNlabelClass 

Pointer 

SmeBSBObjectClass 

See  below 

XtNmappedWhen- 

Boolean 

True 

Whether  xtMapWidget  is  auto 

Managed 

matic 

XtNmenuOnScreen 

Boolean 

True 

See  below 

XtNnumChildren 

Cardinal 

0 

The  number  of  children  in  this 

composite  widget 

XtNoverrideRedirect 

Boolean 

True 

See  below 

XtNpopdownCa  1  Iba  ck 

Callback 

NULL 

See  below 

XtNpopupCallback 

Callback 

NULL 

See  below 

XtNpopupOnEntry 

Widget 

La  be  1   (or  first  entry) 

See  below 

XtNrowHeight 

Dimension 

0 

See  below 

XtNsaveUnder 

Boolean 

False 

See  below 

XtNscreen 

Screen 

Parent's  screen 

Screen  on  which  this  widget  is 

displayed 

XtNsensitive 

Boolean 

True 

Whether  widget  receives  input 

XtNtopMargin 

Dimension 

0 

See  below 

XtNtranslations 

TranslationTable 

NULL 

Event-to-action  translations 

XtNvisual 

Visual 

CopyFromParent 

Visual  type 

XtNwidth 

Dimension 

Width  of  widest  entry 

Menu  width 

XtNx 

Position 

0 

x-coordinate  in  pixels 

XtNy 

Position 

0 

y-coordinate  in  pixels 

XtNbackingStore 

Determines  what  type  of  backing  store  will  be  used  for  the  menu.  Legal  values  for  this 
resource  are  NotUsef  ul,  whenMapped,  and  Always.  These  values  are  the  backing- 
store  integers  defined  in  <XlllX.h>. 

If  default  is  specified  (the  default  behavior)  the  server  will  use  whatever  it  thinks  is 
appropriate. 
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XtNbottomMargin 
XtNtopMargin 

The  amount  of  space  between  the  top  or  bottom  of  the  menu  and  the  menu  entry  closest 

to  that  edge. 

XtNcursor 

The  shape  of  the  mouse  pointer  whenever  it  is  in  this  widget. 

XtNgeometry 

If  this  resource  is  specified,  it  overrides  the  x,  y,  width  and  height  of  this  widget. 
The  format  of  this  string  is  [<width>x<height>][{+  -}  <xoffset>  {+  -}<yoffset>]. 

XtNlabel 

This  label  will  be  placed  at  the  top  of  the  SimpleMenu  and  cannot  be  highlighted.  The 
name  of  the  label  object  is  menuLabel.  Using  this  name,  it  is/possible  to  modify  the 
label's  attributes  through  the  resource  database.  When  the  label  is  created,  the  Xt 
Nlabel  is  hard-coded  to  the  value  of  XtNlabel,  and  xtN  justify  is  hard-coded  as 
XtJustifyCenter. 

XtNlabelClass 

Specifies  the  type  of  Sme  object  created  as  the  menu  label. 

XtNmenuOnScreen 

If  the  menu  is  automatically  positioned  under  the  cursor  with  the  XawPosition- 
SimpleMenu  action,  and  if  this  resource  is  True,  then  the  menu  is  always  fully  visible 
on  the  screen. 

XtNoverrideRedirect 

Determines  the  value  of  the  override_redirect  attribute  of  the  SimpleMenu's  win 
dow.  The  override_redirect  attribute  of  a  window  determines  whether  a  window 
manager  may  interpose  itself  between  this  window  and  the  root  window  of  the  display. 
For  more  information,  see  the  Inter-Client  Communications  Conventions  Manual. 

XtNpopdownCallback 

XtNpopupCallback 

These  callback  functions  are  called  by  the  Xt  Intrinsics  whenever  the  shell  is  popped  up 
or  down.  (See  X  Toolkit  Intrinsics  -  C  Language  Interface  for  details.) 

XtNpopupOnEntry 

The  XawPositionSimpleMenu  action  pops  up  the  SimpleMenu  with  its  label  (or  first 
entry)  directly  under  the  pointer,  by  default.  To  pop  up  the  menu  under  another  entry,  set 
this  resource  to  the  menu  entry  that  should  be  under  the  pointer  when  the  menu  is  popped 
up.  This  allows  the  application  to  offer  the  user  a  default  menu  entry  that  can  be  selected 
without  moving  the  pointer. 

XtNrowHeight 

If  this  resource  is  0  (the  default),  then  each  menu  entry  is  given  its  desired  height.  If  this 
resource  has  any  other  value,  then  all  menu  entries  are  forced  to  be  XtNrowHeight 
pixels  high. 
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XtNsaveUnder 

If  this  is  True,  then  save  unders  will  be  active  on  the  menu's  window. 

Translations  and  Actions 

The  following  default  translation  bindings  are  used  by  the  SimpleMenu  widget: 

<EnterWindow>: highlight ( ) 

<LeaveWindow> : unhighlight ( ) 

<BtnMotion> : highlight { ) 

<BtnUp>:MenuPopdown { )    notify ()    unhighlight ( ) 

With  these  bindings,  the  user  can  pop  down  the  menu  without  activating  any  of  the  callback 
functions,  by  releasing  the  pointer  button  when  no  menu  item  is  highlighted. 

The  SimpleMenu  widget  supports  the  following  actions: 

•  Switching  the  entry  under  the  mouse  pointer  between  the  foreground  and  background 
colors  with  highlight  and  unhighlight. 

•  Processing  menu  entry  callbacks  with  notify. 
The  actions  supported  by  SimpleMenu  are  listed  below: 

highlightQ 

Highlights  the  menu  entry  that  is  currently  under  the  pointer.  Only  an  item  that  is  high 
lighted  is  notified  when  the  notify  action  is  invoked.  The  look  of  a  highlighted  entry 
is  determined  by  the  menu  entry. 

unhighlightQ 

Unhighlights  the  currently  highlighted  menu  item  and  returns  it  to  its  normal  look. 

notify()  ,-' 

Notifies  the  currently  highlighted  menu  entry  that  it  has  been  selected.  It  is  the  responsi 
bility  of  the  menu  entry  to  take  the  appropriate  action. 

MenuPopdown(jnenu) 

Built-in  action  to  pop  down  a  menu  widget 

Positioning  the  SimpleMenu 

If  the  SimpleMenu  widget  is  to  be  used  as  a  pulldown  menu,  then  either  the  MenuButton(S) 
widget  or  some  other  outside  means  should  be  used  to  place  the  menu  when  it  is  popped  up. 

If  pop-up  menus  are  desired  you  must  add  the  XawPositionSimpleMenu  and  XtMenu- 
Popup  actions  to  the  translation  table  of  the  widget  that  will  be  popping  up  the  menu.  Xaw 
PositionSimpleMenu  is  a  global  action  procedure.  It  is  registered  by  the  SimpleMenu 
widget  either  when  the  first  such  action  is  created  or  when  the  convenience  routine  Xaw- 
SimpleMenuAddGlobalActions  is  called. 

For  example,  these  are  the  translations  needed  to  pop  up  some  of  xterm' s  menus: 

Ctrl<BtnlDown>:  XawPositionSimpleMenu (xterm)  XtMenuPopup (xterm) 
Ctrl<Btn2Down>:  XawPositionSimpleMenu (modes)  XtMenuPopup (modes) 
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XawPositionSimpleMenu(merju) 

The  XawPositionSimpleMenu  routine  searches  for  the  menu  name  pas 
sed  to  it  using  XtNameToWidget,  starting  with  the  widget  invoking  the 
action  as  the  reference  widget.  If  unsuccessful,  this  routine  continues  to 
search  up  the  widget  tree,  using  each  of  the  invoking  widget's  ancestors  as 
the  reference  widget  If  still  unsuccessful,  the  routine  prints  a  warning  mes 
sage  and  gives  up.  XawPositionSimpleMenu  positions  the  menu 
directly  under  the  pointer.  The  menu  is  placed  so  that  the  pointer  is  centered 
on  the  entry  named  by  the  popupOnEntry  resource.  If  the  xtNmenu- 
OnScreen  resource  is  True,  then  the  menu  is  always  fully  visible  on  the 
screen. 

Programmatic  Interface 

•  The  XawPositionSimpleMenu  action  routine  can  often  be  invoked  before  any  menus 
have  been  created.  This  can  occur  when  an  application  uses  dynamic  menu  creation.  In 
these  cases  an  application  needs  to  register  this  global  action  routine  by  calling  Xaw- 
SimpleMenuAddGlobalActions: 

void   XawSimpleMenuAddGlobalActions (app_con) 
XtAppContext    app_con; 

where  app_con  specifies  the  application  context  in  which  this  action  should  be  regis 
tered. 

This  function  need  only  be  called  once  per  application  and  must  be  called  before  any 
widget  that  uses  XawPositionSimpleMenu  action  is  realized. 

•  To  get  the  currently  highlighted  menu  entry,  use  XawSimpleMenuGetActiveEntry: 

Widget  XawSimpleMenuGetActiveEntry ( w) 
XtAppContext  w; 

where  w  specifies  the  SimpleMenu  widget 

This  function  returns  either  the  menu  entry  that  is  currently  highlighted  or  NULL  if  no  entry 
is  highlighted. 

•  To  clear  the  SimpleMenu  widget's  internal  information  about  the  currently  highlighted 
menu  entry,  use  XawSimpleMenuClearActiveEntry: 

Widget  XawSimpleMenuClearActiveEntry ( w) 
XtAppContext  w; 

where  w  specifies  the  SimpleMenu  widget 

This  function  unsets  all  internal  references  to  the  currently  highlighted  menu  entry.  It 
does  not  unhighlight  or  otherwise  alter  the  appearance  of  the  active  entry.  This  function  is 
primarily  for  use  by  implementors  of  menu  entries. 

•  To  create  a  SimpleMenu  widget  instance,  use  xtCreateWidget  and  specify  the  class 
variable  smeBSBOb  jectClass. 
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•       To  destroy  a  SimpleMenu  widget  instance,  use  xtDestroyWidget  and  specify  the 
widget  ID  of  the  SimpleMenu  widget 

See  Also 

MenuButton(5),  Sme(5),  SmeBSB(5),  SmeLine(5). 
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Sme 


Name 

Sme  object  —  base  class  for  menu  entries. 


Synopsis 

#include  <Xll/StringDefs ,h> 

#include  <Xll/Intrinsic.h> 

#include  <Xll/Xaw/Sme.h> 

widget  =  XtCreateWidget (name, 


smeOb jectClass, . . . ) 


Class  Hierarchy 

Object  -^  RectObj 


Sme 


Description 

The  Sme  object  is  the  base  class  for  all  menu  entries  that  are  children  of  SimpleMenu.  While 
this  object  is  intended  mainly  to  be  subclassed,  it  may  be  used  in  a  menu  to  add  blank  space 
between  menu  entries. 

Resources 

The  resources  associated  with  the  Sme  object  are  defined  in  this  section  and  affect  only  the 
single  menu  entry  specified  by  this  object. 


Name 

Class  Type 

Default 

Description 

XtNancestor- 

Boolean 

True 

Sensitivity  state  of  the  ancestors  of 

Sensitive 

this  widget:  a  widget  is  insensitive 

if  either  it  or  any  of  its  ancestors  is 

insensitive 

XtNborderWidth 

Dimension 

1 

Width  of  button  border 

XtNcallback 

XtCallbackList 

NULL 

Callback  for  not  if  y  action 

XtNdestroy- 

XtCallbackList 

NULL 

Callbacks  for  XtDestroyWidget 

Callback 

XtNheight 

Dimension 

0 

Object  height 

XtNsensitive 

Boolean 

True 

Whether  widget  receives  input 

XtNwidth 

Dimension 

1 

Object  width 

XtNx 

Position 

0 

x-coordinate  in  pixels 

XtNy 

Position 

0 

y-coordinate  in  pixels 

Keep  in  mind  that  the  SimpleMenu  widget  forces  all  menu  items  to  be  the  width  of  the  widest 
entry. 

Subclassing  the  Sme  Object 

To  create  a  new  Sme  object,  you  must  define  a  few  class  procedures.  These  procedures  allow 
the  SimpleMenu  to  highlight  and  unhighlight  the  menu  entry  as  the  pointer  cursor  moves  over 
it,  as  well  as  notifying  the  entry  when  the  user  has  selected  it 

Three  new  class  methods  are  defined  by  the  Sme  object.  All  of  these  methods  may  be  inherited 
from  the  Sme  object,  although  the  default  semantics  are  not  very  interesting. 
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Highlight ( )          Called  to  put  the  menu  entry  into  the  highlighted  state. 
UnhighlightQ     Called  to  return  the  widget  to  its  normal  (unhighlighted)  state. 
Not i  f  y( )  Called  when  the  user  selects  this  menu  entry. 

Other  than  using  these  specialized  class  procedures,  creating  a  new  object  is  straightforward. 
Just  subclass  Sme  and  define  new  redisplay  and  highlight  procedures.  Here  is  some  informa 
tion  that  can  help  you  avoid  some  common  mistakes. 

1.  Objects  can  be  0  pixels  high. 

2.  Objects  draw  on  their  parent's  window;  therefore,  the  drawing  dimensions  are  different 
from  those  of  widgets.  For  instance,  y  locations  vary  from  y  to  y  +  height,  not  from  0  to 
height. 

3.  XtSetValues  calls  may  come  from  the  application  while  the  SimpleMenu  is  in  its 
notify  procedure.  The  SimpleMenu  may  later  call  the  menu  entry's  unhighlight  pro 
cedure.  Due  to  the  asynchronous  nature  of  X,  the  Expose  event  generated  by  xtSet- 
Values  will  come  after  this  unhighlight. 

4.  Remember,  the  menu  entry  does  not  own  the  window.  Share  the  space  with  other  menu 
entries:  never  draw  outside  your  own  section  of  the  menu. 

Programmatic  Interface 

To  create  an  Sme  object  instance,  use  XtCreateWidget  and  specify  the  class  variable 

smeObjectClass. 

•       To  destroy  an  Sme  object  instance,  use  xtDestroyWidget  and  specify  the  widget  ID  of 
the  Sme  object. 

,,< 
See  Also 

MenuButton(5\  SimpleMenu(5),  SmeBSB(S\  SmeLine(5). 
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SmeBSB 


Name 

SmeBSB  object  —  basic  menu  entry. 

Synopsis 

#include  <Xll/StringDef s.h> 

#include  <Xll/Intrinsic.h> 

#include  <Xll/Xaw/SmeBSB.h> 

widget  -  XtCreateWidget (name,  smeBSBOb jectClass, 


Class  Hierarchy 

Object  ->  RectObj 


Sme  -»  SmeBSB 


Description 

The  SmeBSB  object  is  used  to  create  a  menu  entry  that  contains  a  string,  and  optional  bitmaps 
in  its  left  and  right  margins.  The  parent  is  expected  to  be  SimpleMenu.  Since  each  menu  entry 
is  an  independent  object,  the  application  is  able  to  change  the  font,  color,  height,  and  other 
attributes  of  the  menu  entries,  on  an  entry-by-entry  basis. 

Resources 

The  resources  associated  with  the  SmeBSB  object  are  defined  in  this  section,  and  affect  only 
the  single  menu  entry  specified  by  this  object. 


Name 

Class  Type 

Default 

Description 

XtNancestor- 

Boolean 

True 

Sensitivity  state  of  the  ancestors  of 

Sensitive 

this  widget:  a  widget  is  insensitive 

if  either  it  or  any  of  its  ancestors  is 

insensitive 

XtNborderWidth 

Dimension 

1 

Width  of  button  border 

XtNcallback 

XtCallbackList 

NULL 

Callback  for  not  i  f  y  action 

XtNdestroy- 

XtCallbackList 

NULL 

Callbacks  for  XtDestroyWidget 

Callback 

XtNfont 

XFontStruct* 

XtDefaultFont 

Menu  entry  font 

XtN  foreground 

Pixel 

XtDefault- 

Foreground  color 

Foreground 

XtNheight 

Dimension 

font  height  + 

Menu  entry  height 

XtNvertSpace 

XtNjustify 

Xt  Justify 

XtJustifyCenter 

Type  of  text  alignment 

XtNlabel 

String 

name  of  widget 

Menu  entry  text 

leftBitmap 

Pixmap 

XtUn  specif  ied- 

See  below 

Pixmap 

leftMargin 

Dimension 

4 

See  below 

rightBitmap 

Pixmap 

XtUnspecified- 

See  below 

Pixmap 

rightMargin 

Dimension 

4 

See  below 

XtNsensitive 

Boolean 

True 

Whether  widget  receives  input 

vertSpace 

int 

25 

X  Toolkit  Intrinsics  Reference  Manual 


571 


SmeBSB 
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Name 

Class  Type 

Default 

Description 

XtNwidth 

Dimension 

Text  width  +  margins 

Width  of  menu  entry 

XtNx 

Position 

0 

x  -coordinate  in  pixels 

XtNy 

Position 

0 

y-coordinate  in  pixels 

The  new  resources  (not  inherited  from  superclasses)  associated  with  the  SmeBSB  object  are: 

XtN foreground 

Specifies  a  pixel  value  that  indexes  the  parent's  colormap  to  derive  the  foreground  color  of 
the  menu  entry's  window.  This  color  is  also  used  to  render  all  1's  in  XtNlef  tBitmap 

and  XtNrightBitmap. 

XtNjustify 

Specifies  how  the  label  is  to  be  rendered  between  the  left  and  right  margins  when  the  space 
is  wider  than  the  actual  text  This  resource  may  be  specified  with  the  values  xt- 
JustifyLeft,XtJustifyCenter,orXtJustifyRight.  When  specifying  the  jus 
tification  from  a  resource  file,  the  values  left,  center,  or  right  may  be  used. 

XtNlabel 

Specifies  the  string  to  be  display  in  the  menu  entry.  The  exact  location  of  this  string  within 
the  bounds  of  the  menu  entry  is  controlled  by  the  resources  xtNleftMargin,  xt- 

NrightMargin,  XtNvertSpace,  and  XtNjustify. 

XtNleftBitmap 

XtNrightBitmap 

Specifes  a  name  of  a  bitmap  to  display  in  the  left  or  right  margin  of  the  menu  entry.  All  1  's 
in  the  bitmap  are  rendered  in  the  foreground  color  of  the  SimpleMenu  widget,  and  all  O's 
will  be  drawn  in  the  background  color  of  the  SimpleMenu  widget.  The  programmer  must 
ensure  that  the  menu  entry  is  tall  enough  and  that  the  appropriate  margin  is  wide  enough  to 
accept  the  bitmap.  If  care  is  not  taken,  the  bitmap  might  extend  into  either  another  menu 
entry  or  this  entry's  label. 

XtNleftMargin 
XtNrightMargin 

Specifies  the  amount  of  space  (in  pixels)  to  leave  between  the  edge  of  the  menu  entry  and 

the  label  string. 

XtNvertSpace 

Specifies  the  amount  of  vertical  padding  to  place  around  the  label  of  a  menu  entry.  The 
label  and  bitmaps  are  always  centered  vertically  within  the  menu.  Values  for  this  resource 
are  expressed  as  a  percentage  of  the  font's  height  The  default  value  (25)  increases  the 
default  height  to  125%  of  the  font's  height 
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Programmatic  Interface 

To  create  an  SmeBSB  object  instance,  use  xtCreateWidget  and  specify  the  class  vari 
able  smeBSBOb jectClass. 

•       To  destroy  an  SmeBSB  object  instance,  use  XtDestroyWidget  and  specify  the  widget 
ID  of  the  SmeBSB  object. 

See  Also 

MenuButton(5),  SimpleMenu(5),  Sme(5),  SmeLine(5). 
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Name 

SmeLine  object  —  menu  item  separator. 

Synopsis 

#include  <Xll/StringDefs . h> 

tinclude  <Xll/Intrinsic ,h> 

#include  <Xll/Xaw/SmeLine .h> 

widget  =  XtCreateWidget (name,  smeLineOb jectClass, .  .  . )  ; 

Class  Hierarchy 

Object  ->  RectObj  -»  Sme  ->  SmeLine 

Description 

The  SmeLine  object  is  used  to  add  a  horizontal  line  or  menu  separator  to  a  SimpleMenu.  Since 
each  menu  entry  is  an  independent  object,  the  application  is  able  to  change  the  color,  height, 
and  other  attributes  of  the  menu  entries,  on  an  entry-by-entry  basis.  This  entry  is  not  selectable, 
and  does  not  highlight  when  the  pointer  cursor  is  over  it 

Resources 

The  resources  associated  with  the  SmeLine  object  are  defined  in  this  section,  and  affect  only 
the  single  menu  entry  specified  by  this  object. 


Name 

Class  Type 

Default 

Description 

XtNancestor- 

Boolean 

True 

Sensitivity  state  of  the  ancestors  of 

Sensitive 

this  widget:  a  widget  is  insensitive 

if  either  it  or  any  of  its  ancestors  is 

insensitive 

XtNborderWidth 

Dimension 

1 

Width  of  button  border 

XtNcallback 

XtCallbackList 

NULL 

Callback  for  not  i  f  y  action 

XtNdestroy- 

XtCallbackList 

NULL 

Callbacks  forxtDestroyWidget 

Callback 

XtN  foreground 

Pixel 

XtDefault- 

Foreground  color 

Foreground 

XtNheight 

Dimension 

0 

Object  height 

XtNlineWidth 

Dimension 

1 

See  below 

XtN  sensitive 

Boolean 

True 

Whether  widget  receives  input 

XtNstipple 

Pixmap 

XtUnspecif  ied- 

See  below 

Pixmap 

XtNwidth 

Dimension 

1 

Object  width 

XtNx 

Position 

0 

x-coordinate  in  pixels 

XtNy 

Position 

0 

y-coordinate  in  pixels 

XtN foreground 

A  pixel  value  that  indexes  the  parent's  colormap  to  derive  the  foreground  color  of  the 
menu  entry's  window.  This  color  is  also  used  to  render  all  1's  in  xtNlef  tBitmap  and 
XtNright Bitmap. 
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XtNlineWidth 

The  width  of  the  horizontal  line  to  be  displayed. 

XtNstipple 

If  a  bitmap  is  specified  for  this  resource,  the  line  will  be  stippled  through  it.  This  allows 
the  menu  separator  to  be  rendered  as  something  more  exciting  than  just  a  line.  For 
instance,  if  you  define  a  stipple  that  is  a  chain  link,  then  your  menu  separators  will  look 
like  chains. 

Programmatic  Interface 

•       To  create  an  SmeLine  object  instance,  use  xtCreateWidget  and  specify  the  class  vari 
able  smeLineOb jectClass. 

To  destroy  an  SmeLine  object  instance,  use  xtDestroyWidget  and  specify  the  widget 
ID  of  the  SmeLine  object. 

See  Also 

MenuButton(5),  SimpleMenu(5),  Sme(5),  SmeBSB(5). 
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Name 

StripChart  widget  —  widget  to  display  a  real-time  graphic  chart. 

Synopsis 

#include  <Xll/StringDefs . h> 

#include  <Xll/Intrinsic.h> 

#include  <Xll/Xaw/StripChart .h> 

widget  =  XtCreateWidget (name,  stripChartWidgetClass, 


Class  Hierarchy 
Core  — >  Simple 


StripChart 


Description 

The  StripChart  widget  is  used  to  provide  a  real-time  graphic  chart  of  a  single  value.  This 
widget  is  used  by  xload  to  provide  the  load  graph.  It  will  read  data  from  an  application,  and 
update  the  chart  at  the  xtNupdate  interval  specified. 

Resources 

When  creating  a  StripChart  widget  instance,  the  following  resources  are  retrieved  from  the 
argument  list  or  from  the  resource  database: 


Name 

Class  Type 

Default 

Description 

XtNaccelerators 

AcceleratorTable 

NULL 

List  of  event-to-action  bindings  to 

be  executed  by  this  widget,  even 

though    the    event    occurred    in 

another  widget 

XtNancestor- 

Boolean 

True 

Sensitivity  state  of  the  ancestors  of 

Sensitive 

this  widget:  a  'widget  is  insensitive 

if  either  it  or  any  of  its  ancestors  is 

insensitive 

XtNbackground 

Pixel 

XtDefault- 

Window  background  color 

Background 

XtNbackground- 

Pixmap 

XtUnspecified- 

Window  background  pixmap 

Pixmap 

Pixmap 

XtNborderColor 

Pixel 

XtDefault- 

Window  border  color 

Foreground 

XtNborderPixmap 

Pixmap 

XtUnspeci  f  ied- 

Window  border  pixmap 

Pixmap 

XtNborderWidth 

Dimension 

1 

Border  width  in  pixels 

XtNcolormap 

Colormap 

Parent's  colormap 

Colormap  that  this  widget  will  use 

XtNcursor 

Cursor 

None 

Pointer  cursor 

XtNdepth 

int 

Parent's  depth 

Depth  of  this  widget's  window 

XtNdestroy- 

XtCallbackList 

NULL 

Callbacks  for  XtDestroyWidget 

Callback 

XtN  foreground 

Pixel 

XtDefault- 

Foreground  color 

Foreground 

XtNgetValue 

Callback 

NULL 

See  below 
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(continued) 


StripChart 


Name 

Class  Type 

Default 

Description 

XtNheight 

Dimension 

Font  height  +  2  * 

Height  of  widget 

XtNinternal- 

Height 

XtNhighlight 

Pixel 

XtDefault- 

See  below 

Foreground 

XtNinsensitive- 

Pixmap 

GrayPixmap 

Border  when  not  sensitive 

Border 

XtN  jumpScroll 

int 

half  the  width  of  the 

See  below 

widget 

XtNmappedWhen- 

Boolean 

TRUE 

Whether  XtMapWidget  is  auto- 

Managed 

made 

XtNminScale 

int 

1 

See  below 

XtNscreen 

Screen 

Parent's  screen 

Screen   on   which   this   widget  is 

displayed.    This  is  not  a  sellable 

resource 

XtNsensitive 

Boolean 

TRUE 

Whether  widgel  receives  inpul 

XtNtranslations 

Translation- 

See  below 

Eveni-io-aclion  translalions 

Table 

XtNupdate 

int 

10 

See  below 

XtNwidth 

Dimension 

0 

The  heighl  and  widlh  of  ihis  widgel 

in  pixels 

XtNx 

Position 

0 

x-coordinate  in  pixels 

XtNy 

Position 

0 

y-coordinate  in  pixels 

The  new  resources  (not  inherited  from  superclasses)  associated  with  the  StipChart  widget  are: 

xtNget Value  This  is  a  list  of  functions  to  call  every  XtNupdate  seconds.  This  function 
will  get  the  value  to  be  graphed  by  the  StripChart  widget.  The  section 
below,  Getting  the  StripChart  Value  describes  the  calling  interface  in  more 
detail.  This  callback  list  should  contain  only  one  function.  If  this  callback 
list  contains  more  than  one  function,  the  behavior  is  undefined. 

XtNhighlight  A  pixel  value  which  indexes  the  widget's  colormap  to  derive  the  color  that 
will  be  used  to  draw  the  scale  lines  on  the  graph. 

XtN  jumpScroll  When  the  graph  reaches  the  right  edge  of  the  window  it  must  be  scrolled  to 
the  left.  This  resources  specifies  the  number  of  pixels  it  will  jump.  Smooth 
scrolling  can  be  achieved  by  setting  this  resource  to  1. 

The  minimum  scale  for  the  graph.  The  number  of  divisions  on  the  graph  will 
always  be  greater  than  or  equal  to  this  value. 

The  number  of  seconds  between  graph  updates.  Each  update  is  represented 
on  the  graph  as  a  1  pixel  wide  line.  Every  XtNupdate  seconds  the  get- 
Value  procedure  will  be  used  to  get  a  new  graph  point,  and  this  point  will 
be  added  to  the  right  end  of  the  StripChart. 


XtNminScale 


XtNupdate 
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Getting  The  StripChart  Value 

The  StripChart  widget  will  call  the  application  routine  passed  to  it  as  the  xtNgetValue  call 
back  function  every  xtNupdate  seconds  to  obtain  another  point  for  the  StripChart  graph. 
The  calling  interface  for  the  XtNgetValue  callback  is: 

void    (*getValueProc)  (w,    client_data,    value) 
Widget    w; 

XtPointer    client_data; 
XtPointer    value;  I*   double    *    */ 

w  Specifies  the  StripChart  widget 

cl ient_data  Specifies  the  client  data. 

value  Returns  a  pointer  to  a  double.  The  application  should  set  the  address  pointed 

to  by  this  argument  to  a  double  containing  the  value  to  be  graphed  on  the 
StripChart. 

This  function  is  used  by  the  StripChart  to  call  an  application  routine.  The  routine  will  pass  the 
value  to  be  graphed  back  to  the  the  StripChart  in  the  value  field  of  this  routine. 

Programmatic  Interface 

To  create  a  StripChart  widget  instance,  use  xtCreateWidget  and  specify  the  class  vari 
able  stripChartWidgetClass. 

To  destroy  a  StripChart  widget  instance,  use  xtDestroyWidget  and  specify  the  widget 
ID  of  the  StripChart. 
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Name 

Template  widget  —  widget  to  create  a  custom  widget. 

Synopsis 

#include  <Xll/StringDef s.h> 
tinclude  <Xll/Intrinsic.h> 
#include  <Xll/Xaw/Template .h> 

Description 

Although  the  task  of  creating  a  new  widget  may  at  first  appear  a  little  daunting,  there  is  a  basic 
pattern  that  all  widgets  follow.  The  Athena  widget  library  contains  three  files  that  are  intended 
to  assist  in  writing  a  custom  widget  Template.h,  TemplateP.h,  and  Templates.  However,  it 
may  be  easier  to  start  with  a  widget  that  has  more  real  code  to  copy  and  modify. 

Reasons  for  wishing  to  write  a  custom  widget  include: 

•  Convenient  access  to  resource  management  procedures  to  obtain  fonts,  colors,  etc.,  even  if 
user  customization  is  not  desired. 

•  Convenient  access  to  user  input  dispatch  and  translation  management  procedures. 

•  Access  to  callback  mechanisms  for  building  higher-level  application  libraries. 

•  Customizing  the  interface  or  behavior  of  an  existing  widget  to  suit  a  special  application 
need. 

•  Desire  to  allow  user  customization  of  resources  such  as  fonts,  colors,  etc.,  or  to  allow  con 
venient  re-binding  of  keys  and  buttons  to  internal  functions. 

•  Converting  a  non-Toolkit  application  to  use  the  Toolkit 

In  each  of  these  cases,  the  operation  needed  to  create  a  new  widget  is  to  "subclass"  an  existing 
one.  If  the  desired  semantics  of  the  new  widget  are  similar  to  an  existing  one,  then  the  imple 
mentation  of  the  existing  widget  should  be  examined  to  see  how  much  work  would  be  required 
to  create  a  subclass  that  will  then  be  able  to  share  the  existing  class  methods.  Much  time  will 
be  saved  in  writing  the  new  widget  if  an  existing  widget  class's  Expose,  Resize,  and/or 
GeometryManager  method  can  be  shared  by  the  subclass. 

Note  that  some  trivial  uses  of  a  "bare-bones"  widget  may  be  achieved  simply  by  creating  an 
instance  of  the  Core  widget  The  class  variable  to  use  when  creating  a  Core  widget  is 
widgetClass.  The  geometry  of  the  Core  widget  is  determined  entirely  by  the  parent  widget. 

Often,  an  application  will  need  a  certain  set  of  functions — and  many  copies  of  them.  For 
example,  when  converting  an  older  application  to  use  the  Toolkit,  it  may  be  desirable  to  have  a 
"Window  widget"  class  that  might  have  the  following  semantics: 

•  Allocate  two  drawing  colors  in  addition  to  a  background  color. 

•  Allocate  a  text  font 
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•  Execute  an  application-supplied  function  to  handle  exposure  events. 

•  Execute  an  application-supplied  function  to  handle  user  input  events. 

Of  course,  a  completely  general-purpose  windowWidgetClass  could  be  constructed  to 
export  all  class  methods  as  callback  lists,  but  such  a  widget  would  be  very  large  and  would 
have  to  choose  some  arbitrary  number  of  resources,  such  as  colors,  to  allocate.  An  application 
that  used  many  instances  of  the  general-purpose  widget  would  therefore  waste  many  resources 
unnecessarily. 

This  section  outlines  the  procedure  to  follow  to  construct  a  special-purpose  widget  to  address 
the  items  listed  above.  The  reader  should  refer  to  the  appropriate  sections  of  Volume  Four,  X 
Toolkit  Intrinsics  Programming  Manual,  for  complete  details  of  the  material  outlined  here. 

All  Athena  widgets  have  three  separate  files  associated  with  them: 

•  A  public  header  file  containing  declarations  needed  by  applications  programmers. 

•  A  private  header  file  containing  additional  declarations  needed  by  the  widget  and  any  sub 
classes. 

•  A  source  code  file  containing  the  implementation  of  the  widget. 

This  separation  of  functions  into  three  files  is  suggested  for  all  widgets,  but  nothing  in  the 
Toolkit  actually  requires  this  format.  In  particular,  a  private  widget  created  for  a  single  applica 
tion  may  easily  combine  the  public  and  private  header  files  into  a  single  file,  or  merge  the  con 
tents  into  another  application  header  file.  Similarly,  the  widget  implementation  can  be  merged 
into  other  application  code. 

In  the  following  example,  the  public  header  file  <XlllXaw /Template. h>,  the  private  header  file 
<Xll/Xa\v/TemplateP.h>,  and  the  source  code  file  <Xll/Xa\v/Template.c>  are  modified  to  pro 
duce  the  Window  widget  described  above.  In  each  case,  the  files  have  been  designed  so  that 
you  can  make  a  global  string  replacement  of  Template  and  template  with  the  name  of  your  new 
widget,  using  the  appropriate  case. 

Public  Header  File 

The  public  header  file  contains  declarations  that  will  be  required  by  any  application  module 
that  needs  to  refer  to  the  widget;  whether  to  create  an  instance  of  the  class,  to  perform  an  xt- 
SetValues  operation,  or  to  call  a  public  routine  implemented  by  the  widget  class. 

The  contents  of  the  Template  public  header  file,  <Xll/Xaw/Template.h>,  are: 

#ifndef  _Template_h 
#define  _Template_h 


* 

*    Template   widget 


******** 
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Template 


Class 


RepType 


Default  Value 


/*  Resources: 

Name 

background 

border 

borderWidth 

destroyCallback 

height 

mappedWhenManaged 

sensitive 

width 


*/ 

/*  define  any  special  resource  names  here  * 
*  that  are  not  in  <Xll/StringDef s ,h>  */ 

#define  XtNtemplateResource  "templateResource" 

tdefine  XtCTemplateResource          "TemplateResource" 
/*  declare  specific  TemplateWidget  class  and  instance  datatypes  */ 


Background 
BorderColor 
BorderWidth 
Callback 
Height 
MappedWhenManaged 
Sensitive 
Width 
Position 
Position 

Pixel 
Pixel 
Dimension 
Pointer 
Dimension 
Boolean 
Boolean 
Dimension 
Position 
Position 

Xt  Default  Background 
Xt  Default  Foreground 
1 
NULL 
0 
TRUE 
TRUE 
0 
0 
0 

typedef  struct  _TemplateClassRec' 
typedef  struct  _TemplateRec* 


TemplateWidget Class; 
TemplateWidget  ; 


/*  declare  the  class  constant  */ 
extern  WidgetClass  templateWidgetClass; 
tendif   _Template_h 

You  will  notice  that  most  of  this  file  is  documentation.  The  crucial  parts  are  the  last  8  lines, 
where  macros  for  any  private  resource  names  and  classes  are  defined  and  where  the  widget 
class  datatypes  and  class  record  pointer  are  declared. 

For  the  Window  widget,  we  want  two  drawing  colors,  a  callback  list  for  user  input  and  an  xt- 
NexposeCallback  callback  list,  and  we  will  declare  three  convenience  procedures,  so  we 
need  to  add: 

/*  Resources: 


callback 

drawingColorl 

drawingColor2 

exposeCallback 

font 

*/ 


#define  XtNdrawingColorl 
#define  XtNdrawingColor2 


Callback 

Callback 

Color 

Pixel 

Color 

Pixel 

Callback 

Callback 

Font 

XFontStr 

NULL 

Xt Default Foreground 

Xt  Default For eg round 
NULL 


"drawingColorl " 
"drawingColor2" 
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tdefine   XtNexposeCallback       "exposeCallback" 

extern  Pixel  WindowColorl ( /*  Widget  */ ) ; 
extern  Pixel  WindowColor2 ( /*  Widget  */ ) ; 
extern  Font  WindowFont ( /*  Widget  */ ) ; 

Note  that  we  have  chosen  to  call  the  input  callback  list  by  its  generic  name,  xtNcallback, 
rather  than  by  a  specific  name.  If  widgets  that  define  a  single  user-input  action  all  choose  the 
same  resource  name,  then  there  is  greater  possibility  for  an  application  to  switch  between  widg 
ets  of  different  types. 

Private  Header  File 

The  private  header  file  contains  the  complete  declaration  of  the  class  and  instance  structures  for 
the  widget  and  any  additional  private  data  that  will  be  required  by  anticipated  subclasses  of  the 
widget  Information  in  the  private  header  file  is  normally  hidden  from  the  application  and  is 
designed  to  be  accessed  only  through  other  public  procedures,  such  as  xtSetValues. 

The  contents  of  the  Template  private  header  file,  <Xll/Xaw/TemplateP.h>,  are: 

#ifndef  _TemplateP_h 
#define  _TemplateP_h 

#i    "Template. h" 

/*  include  superclass  private  header  file  */ 

tinclude  <Xll/Xaw/CoreP .h> 

/*  define  unique  representation  types  not  found  in  <Xll/StringDef s . h>  */ 
tdefine  XtRTemplateResource       "TemplateResource" 

typedef  struct  { 

int  empty;  v< 

}  TemplateClassPart; 

typedef  struct  _TemplateClassRec  { 

CoreClassPart  core_class; 

TemplateClassParttemplate_class; 
}  TemplateClassRec; 

extern  TemplateClassRec  templateClassRec; 

typedef  struct  { 

/*  resources  */ 

char*  resource; 

/*  private  state  */ 
}  TemplatePart; 

typedef  struct  _TemplateRec  { 

CorePart      core; 

TemplatePart  template; 
}  TemplateRec; 

#endif  _TemplateP_h 
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The  private  header  file  includes  the  private  header  file  of  its  superclass,  thereby  exposing  the 
entire  internal  structure  of  the  widget  It  may  not  always  be  advantageous  to  do  this;  your  own 
project  development  style  will  dictate  the  appropriate  level  of  detail  to  expose  in  each  module. 

The  Window  widget  needs  to  declare  two  fields  in  its  instance  structure  to  hold  the  drawing 
colors  —  a  resource  field  for  the  font,  and  a  field  for  the  expose  and  user  input  callback  lists: 

typedef  struct  { 

/*  resources  */ 

Pixel  color_l; 

Pixel  color_2; 

XFont  Struct*  font; 

XtCallbackList  expose_callback; 

XtCallbackList  input_callback; 

/*  private  state  */ 

/*  (none)  */ 
}  WindowPart; 

Widget  Source  File 

The  source  code  file  implements  the  widget  class  itself.  The  unique  part  of  this  file  is  the  decla 
ration  and  initialization  of  the  widget  class  record  structure  and  the  declaration  of  all  resources 
and  action  routines  added  by  the  widget  class. 

The  contents  of  the  Template  implementation  file,  <XlllXaw  '/Template.  c>,  are: 

#include  <Xll/IntrinsicP  .h> 
#include  <Xll/StringDef  s.h> 
#include  "TemplateP  .h" 

static  XtResource  resources!]  =  { 

#define  of  f  set  (field)  XtOf  fset  (TemplateWidget,  template  .  Peeld) 

/*  {name,  class,  type,  size,  offset,  default_type,  default_addr  }  ,  */ 
{  XtNtemplateResource,  XtCTemplateResource,  XtRTemplateResource,  \ 
sizeof  (char*)  ,  of  fset  (resource)  ,  XtRString,  "default"  }, 

tundef  offset 


static  void  TemplateAction  (/*  Widget,  XEvent*,  String*,  Cardinal*  */) 

static  XtActionsRec  actions!]  = 
{ 

/*  {name,  procedure},  */ 

{"template",  TemplateAction}, 


static  char  translations!] 
"    <Key>:  template  ()  \n\ 
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TemplateClassRec  templateClassRec  =  { 
{    /*  core  fields  */ 
/*  superclass  */ 
/*  class_name  */ 
/*  widget_size  */ 
/*  class_initialize  */ 
/*  class_part_initialize  */ 
/*  class_inited  */ 
/*  initialize  */ 
/*  initialize_hook  */ 
/*  realize  */ 
/*  actions  */ 
/*  num_actions  */ 
/*  resources  */ 
/*  num_resources  */ 
/*  xrm_class  */ 
/*  compress_motion  */ 
/*  compress_exposure  */ 
/*  compress_enterleave  */ 
/*  visible_interest  */ 
/*  destroy  */ 
/*  resize  */ 
/*  expose  */ 
/*  set_values  */ 
/*  set_values_hook  */ 
/*  set_values_almost  */ 
/*  get_values_hook  */ 
/*  accept_focus  */ 
/*  version  */ 
/*  callback_jprivate  */ 
/*  tm_table  */ 
/*  query_geometry  */ 
/*  display_accelerator  */ 
/*  extension  */ 

{  /*  template  fields  */ 
/*  empty  */ 


(WidgetClass)  SwidgetClassRec, 

"Template", 

sizeof (TemplateRec) , 

NULL, 

NULL, 

FALSE, 

NULL, 

NULL, 

XtlnheritRealize, 

actions, 

XtNumber (actions) , 

resources, 

XtNumber (resources)  , 

NULLQUARK, 

TRUE, 

TRUE, 

TRUE, 

FALSE, 

NULL, 

NULL, 

NULL, 

NULL, 

NULL, 

Xt Inner it SetValuesAlmost, 

NULL, 

NULL, 

XtVersion, 

NULL, 

translations, 

Xt Inner itQueryGeometry, 

Xt Inner itDisplayAccelerat or, 

NULL 


WidgetClass  templateWidgetClass  =  (WidgetClass) StemplateClassRec; 

The  resource  list  for  the  Window  widget  might  look  like  the  following: 

static  XtResource  resources []  =  { 

tdefine  of f set (field)  XtOf f set (WindowWidget,  window. Peeld) 

/*  {name,  class,  type,  size,  offset,  default_type,  default_addr } ,  */ 
{  XtNdrawingColorl,  XtCColor,  XtRPixel,  sizeof (Pixel) , 

offset (color_l) ,  XtRString,  XtDefaultForeground  }, 
{  XtNdrawingColor2,  XtCColor,  XtRPixel,  sizeof (Pixel) , 

offset (color  2),  XtRString,  XtDefaultForeground  }, 
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{    XtNfont,    XtCFont,    XtRFont Struct,    sizeof (XFontStruct*) , 

offset (font) ,    XtRString,    XtDefaultFont    }, 
{    XtNexposeCallback,    XtCCallback,    XtRCallback,    sizeof (XtCallbackList) , 

offset (expose_callback) ,    XtRCallback,    NULL    }, 
{    XtNcallback,    XtCCallback,    XtRCallback,    sizeof (XtCallbackList) , 

offset (input_callback) ,    XtRCallback,    NULL    }, 
#undef   offset 
}; 

The  user  input  callback  will  be  implemented  by  an  action  procedure  that  passes  the  event 
pointer  as  call_data.  The  action  procedure  is  declared  as: 

/*  ARGSUSED  */ 

static  void  InputAction (w,  event,  params,  numjparams) 

Widget  w; 

XEvent  *event; 

String  *params;/*  unused  */ 

Cardinal  *num_params; /*  unused  */ 
{ 

XtCallCallbacks(w,  XtNcallback,  (caddr_t) event) ; 

} 

static  XtActionsRec  actions []  = 

{ 

/*  {name,  procedure},  */ 

{"input",  InputAction}, 
}; 

and  the  default  input  binding  will  be  to  execute  the  input  callbacks  on  KeyPress  and 
ButtonPress: 

static   char  translations []    = 
"        <Key>: input (  )    \n\ 

<BtnDown> : input ( )    \ 
it . 

In  the  class  record  declaration  and  initialization,  the  only  field  that  is  different  from  the  Tem 
plate  is  the  expose  procedure: 

/*  ARGSUSED  */ 

static  void  Redisplay (w,  event,  region) 

Widget  w; 

XEvent  *event;    /*  unused  */ 

Region  region; 
{ 

XtCallCallbacks (w,  XtNexposeCallback,  (caddr_t) region) ; 
} 
WindowClassRec  windowClassRec  =  { 

/*  expose  */   Redisplay, 
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The  Window  widget  will  also  declare  three  public  procedures  to  return  the  drawing  colors  and 
the  font  ID,  saving  the  application  the  effort  of  constructing  an  argument  list  for  a  call  to  xt- 

GetValues: 

Pixel  WindowColorl (w) 

Widget  w; 
{ 

return  ( (WindowWidget ) w) ->window . color_l ; 

} 

Pixel  WindowColor2 (w) 

Widget  w; 
{ 

return  ( (WindowWidget ) w) ->window . color_2 ; 

} 

Font  WindowFont (w) 

Widget  w; 
{ 

return  ( (WindowWidget) w) ->window. font->f id; 

} 

The  Window  widget  is  now  complete.  The  application  can  retrieve  the  two  drawing  colors 
from  the  widget  instance  by  calling  either  the  XtGetValues  or  the  windowColor  func 
tions.  The  actual  window  created  for  the  Window  widget  is  available  by  calling  the  xt- 
Window  function. 
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Name 

Text  widget  —  text-editing  widget 

Synopsis 

Mnclude  <Xll/StringDef s .h> 

#include  <Xll/Intrinsic.h> 

#include  <Xll/Xaw/Text .h> 

#include  <Xll/Xaw/AsciiText .h> 

widget  =  XtCreateWidget (name,  textWidgetClass, . . . ) ; 

widget  =  XtCreateWidget (name,  asciiTextWidgetClass, .  .  . )  ; 

Class  Hierarchy 

Core  —>  Simple  — >  Text  ->  AsciiText 

Description 

A  Text  widget  is  a  window  that  provides  a  way  for  an  application  to  display  one  or  more  lines 
of  text  The  displayed  text  can  reside  in  a  file  on  disk  or  in  a  string  in  memory.  An  option  also 
lets  an  application  display  a  vertical  Scrollbar  in  the  Text  window,  letting  the  user  scroll 
through  the  displayed  text.  Other  options  allow  an  application  to  let  the  user  modify  the  text  in 
the  window  or  search  for  a  specific  string. 

The  Text  widget  is  divided  into  three  parts: 

•  Source  object 

•  Sink  object 

•  Text  widget 

The  idea  is  to  separate  the  storage  of  the  text  (source)  from  the  painting  of  the  text  (sink).  The 
Text  widget  proper  coordinates  the  sources  and  sinks.  The  AsciiText  widget  is  a  subclass  of  the 
Text  widget  that  automatically  creates  the  source  and  sink  for  the  client.  By  default,  the  Ascii 
Text  widget  uses  a  string  in  memory  as  the  source;  setting  the  asciiSrc .  type  resource  to 
XawAsciiFile  specifies  use  of  a  disk  file.  The  AsciiText's  sink  is  a  single-font,  single-color 
ASCII  sink.  A  client  can,  if  it  so  chooses,  explicitly  create  the  source  and  sink  before  creating 
the  Text  widget. 

The  source  stores  and  manipulates  the  text,  and  determines  what  editing  functions  may  be  per 
formed  on  the  text 

The  sink  obtains  the  fonts  and  the  colors  in  which  to  paint  the  text.  The  sink  also  computes 
what  text  can  fit  on  each  line. 

If  a  string  in  memory  is  used  as  the  source,  the  application  must  allocate  the  amount  of  space 
needed.  If  a  disk  source  is  used,  the  file  will  not  be  updated  until  a  call  to  XawAsciiSave  is 
made.  When  a  disk  source  is  being  used,  the  useStringlnPlace  resource  is  ignored. 
Three  types  of  edit  mode  are  available: 

•  Append-only 

•  Read-only 
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•     Editable 

Append-only  mode  lets  the  user  enter  text  into  the  window,  while  read-only  mode  does  not. 
Text  may  be  entered  only  if  the  insertion  point  is  after  the  last  character  in  the  window.  Edit 
able  mode  lets  the  user  place  the  cursor  anywhere  in  the  text  and  modify  the  text  at  that  posi 
tion.  The  text  cursor  position  can  be  modified  by  using  the  keystrokes  or  pointer  buttons 
defined  by  the  event  bindings.  (See  Translations  and  Actions  below.) 

Resources 

When  creating  a  Text  widget  instance,  the  following  resources  are  retrieved  from  the  argument 
list  or  from  the  resource  database: 


Name 

Type 

Default 

Description 

XtNaccelerators 

AcceleratorTable 

NULL 

List  of  event-to-action  bindings  to 
be  executed  by  this  widget,  even 
though  the  event  occurred  in 
another  widget 

XtNancestor- 
Sensitive 

Boolean 

True 

Sensitivity  state  of  the  ancestors 
of  this  widget:  a  widget  is  insensi 
tive  if  either  it  or  any  of  its  ances 

tors  is  insensitive 

XtNautoFill 

Boolean 

False 

Specifies  whether  the  Text  widget 
will  automatically  break  a  line 
when  the  user  attempts  to  type 
into  the  right  margin 

XtNbackground 

Pixel 

XtDefault- 
Background 

Window  background  color 

XtNba  ckground- 
Pixmap 

Pixmap 

None 

Window  background  pixmap 

XtNborderColor 

Pixel 

XtDefault- 

Window  border  color 

Foreground 

XtNborderPixmap 

Pixmap 

None 

Window  border  pixmap 

XtNborderWidth 

Dimension 

4 

Border  width  in  pixels 

XtNbottomMargin 

Position 

2 

Amount  of  space,  in  pixels, 
between  the  edge  of  the  window 
and  the  edge  of  the  text  within  the 
window 

AsciiText  .XtNcallback 

XtCallbackList 

NULL 

List  of  callbacks  called  every  time 
the  text  buffer  changes 

XtNcolormap 

Colormap 

Parent's  colormap 

Colormap  that  this  widget  will  use 

XtNcursor 

Cursor 

XC  xterm 

Pointer  cursor 

XtNdataCompression 

Boolean 

True 

If  True,  the  AsciiSrc  will 
compress  its  data  to  the  minimum 
size  required  every  time  the  text 
string  is  saved,  or  the  value  of  the 
string  is  queried 

XtNdepth 

int 

Parent's  depth 

Depth  of  this  widget's  window 

XtNdestroy- 
Callback 

XtCallbackList 

NULL 

Callbacks  for  XtDestroy- 
Widget 

XtNdisplayCaret 

Boolean 

True 

Whether  to  display  the  text  caret 
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Name 


Type 
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Default 


Text 


Description 


AsciiText .XtNdisplay- 
Nonprinting 


XtNdisplayPosition 
AsciiText. XtNecho 

AsciiText .XtNeditType 
AsciiSink .XtNforeground 
AsciiText. XtNfont 
AsciiText. XtNforeground 


XtNheight 
XtNinsensitiveBorder 


XtNinsertPosition 
XtNleftMargin 
AsciiText. XtNlength 

XtNmappedWhen- 
Managed 

AsciiText .XtNpieceSize 


XtNresize 


XtNrightMargin 


XtNscreen 


XtNscrollHorizontal 
XtNscrollVertical 


Boolean 


Int 

Boolean 

XawEditType 
Pixel 

XFontStruct* 
Pixel 


Dimension 
Pixmap 

int 

Dimension 
int 
Boolean 

XawText Posit ion 
XawTextResizeMode 


Position 


Screen 


XawText  Scrol IMode 
XawText ScrollMode 


True 


0 
True 

XawtextRead 

Black 

Fixed 

XtDe fault Foreground 


Font  height 

GreyPixmap 

0 
2 

String  length 

TRUE 
BUFSIZ 

XawtextResizeNever 


Parent's  screen 


Xawtext Scrol INever 
Xawtext Scrol INever 


XtNselectTypes 


XawText Select Type* 


See  below 


Whether  to  display  a  nonprintable 

character   as    the    string    *@:    if 

False,  it  will  be  printed  as  a 

blank 

Character  position  of  first  line 

Whether  or  not  to  echo  characters 

to  the  screen 

Edit  mode  (see  note) 

Foreground  color 

Fontname 

Pixel   value    which   indexes   the 
Text  widget's  colormap  to  derive 
the  foreground  color  used  by  the 
text  sink 
Height  of  widget 

Pixmap    will    be    tiled    into    the 
widget's    border    if    the    widget 
becomes  insensitive 
Character  position  of  caret 
Left  margin  in  pixels 
Size  of  the  string  buffer 
Whether  XtMapWidget  is  auto 
matic 

Size  of  the  internal  chunks  into 
which  the  text  buffer  is  broken 
down  for  memory  management 
Whether  the  widget  should 
attempt  to  resize  to  its  preferred 
dimensions  whenever  its 
resources  are  modified  with  Xt- 
SetValues 

Amount  of  space,  in  pixels, 
between  the  edge  of  the  window 
and  the  corresponding  edge  of  the 
text  within  the  window 
Screen  on  which  this  widget  is 
displayed:  this  is  not  a  sellable 
resource 

See XtNscrollVertical 
Conlrol      ihe      placement      of 
scrollbars  on  the  left  and  bottom 
edge   of  the  text  widget:   these 
resources      accept     the     values 
Xawtext Scroll Always, 
Xawtext Scroll When- 
Needed,        and        Xawtext- 
ScrollNever 
Selection  units  for  multi-click 
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Name 


Type 


Default 


Description 


XtNsensitive 

AsciiText.XtNstring 

XtNtextSink 

XtNtextSource 

XtNtopMargin 


XtNtranslations 
XtNtype 

XtNuseStringlnPlace 


XtNwidth 
AsciiText .XtNwrap 


Boolean 

String 

Widget 

Widget 

Position 


TranslationTable 
AsciiType 

Boolean 


Dimension 
WrapMode 


TRUE 
NULL 

None 
None 
2 


See  above 

XawAsci iSt ring 
False 


100 
XawtextWrapNever 


XtNx 
XtNy 


Position 
Position 


Whether  widget  receives  input 
String  for  the  text  source 
See  below 
See  below 

Amount    of    space,    in    pixels, 
between  the  edge  of  the  window 
and  the  corresponding  edge  of  the 
text  within  the  window 
Event-to-action  translations 
May     be     either     XawAsci i- 
String  or  XawAsciiFile 

If  True,  will  disable  the  memory 
management  provided  by  the  Text 
widget,  updating  the  string 
resource  in  place 
Width  of  widget  (pixels) 
Accepted  values  are  Xawtext 
WrapNever,  XawtextWrap- 
Line,  and  XawtextWrap- 
Word:  with  XawtextWrap- 
Line,  all  text  that  is  beyond  the 
right  edge  of  the  window  will  be 
displayed  on  the  next  line;  with 
XawtextWrapWord,  the  same 
action  occurs  but  the  text  is  bro 
ken  at  a  word  boundary  if  pos 
sible.  If  no  wrapping  is  enabled, 
then  the  text  will  extend  off  the 
edge  of  the  window  and  a  small 
rectangle  will  be  painted  in  the 
right  margin  to  alert  the  user  that 
this  line  is  too  long 
x  coordinate  in  pixels 
y  coordinate  in  pixels 


Note  that 

1.  The  xtNeditType  attribute  has  one  of  the  values  XawtextAppend,  XawtextEdit, 
or  XawtextRead. 

2.  The  value  of  the  XtNtype  resource  determines  whether  the  xtNstring  resource  con 
tains  the  name  of  a  file  to  be  opened  or  a  buffer  to  be  displayed  by  the  Text  widget.  A 
converter  has  been  registered  for  this  resource  and  accepts  the  values  string  and 
file. 

Selections 

xtNselectionTypes  is  an  array  of  entries  of  type  XawTextSelectType  and  is  used  for 
multiclick.  As  the  pointer  button  is  clicked  in  rapid  succession,  each  click  highlights  the  next 
"type"  described  in  the  array. 
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XawselectAll 

Selects  the  contents  of  the  entire  buffer. 

XawselectChar 

Selects  text  characters  as  the  pointer  moves  over  them. 

XawselectLine 

Selects  the  entire  line. 

XawselectNull 

Indicates  the  end  of  the  selection  array. 

XawselectParagraph 

Selects  the  entire  paragraph  (delimited  by  newline  characters). 

Xawselect Posit ion 

Selects  the  current  pointer  position. 

XawselectWord 

Selects  whole  words  (delimited  by  whitespace)  as  the  pointer  moves  onto  them. 
The  default  select  Type  array  is: 

{XawselectPosition,  XawselectWord,  XawselectLine,  XawselectParagraph, 
XawselectAll,  XawselectNull} 

For  the  default  case,  two  rapid  pointer  clicks  highlight  the  current  word,  three  clicks  highlight 
the  current  line,  four  clicks  highlight  the  current  paragraph,  and  five  clicks  highlight  the  entire 
text  If  the  timeout  value  is  exceeded,  the  next  pointer  click  returns  to  the  first  entry  in  the 
selection  array.  The  selection  array  is  not  copied  by  the  Text  widget  The  client  must  allocate 
space  for  the  array  and  cannot  deallocate  or  change  it  until  the  Text  widget  is  destroyed  or  until 
a  new  selection  array  is  set 

To  modify  the  selections,  a  programmer  must  construct  a  XawText  Select  Type  array  (called 
the  selection  array)  containing  the  selections  desired  and  pass  this  as  the  new  value  for  the  xt- 
NselectionTypes  resource.  The  selection  array  may  also  be  modified  using  the  Xaw- 
TextSetSelectionArray  function.  All  selection  arrays  must  end  with  the  value 
XawselectNull.  The  selectionTypes  resource  has  no  converter  registered  and  cannot 
be  modified  through  the  resource  manager. 

The  array  contains  a  list  of  entries  that  will  be  called  when  the  user  attempts  to  select  text  in 
rapid  succession  with  the  select-start  action  (usually  by  clicking  a  pointer  button).  The 
first  entry  in  the  selection  array  will  be  used  when  the  select-start  action  is  initially 
called.  The  next  entry  will  be  used  when  select -start  is  called  again,  and  so  on.  If  a 
timeout  value  (1/10  of  a  second)  is  exceeded,  the  next  select-start  action  will  begin  at 
the  top  of  the  selection  array.  When  XawselectNull  is  reached,  the  array  is  recycled  begin 
ning  with  the  first  element. 

Translations  and  Actions 

Many  standard  keyboard  editing  facilities  are  supported  by  the  event  bindings.  The  following 
actions  are  supported: 
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Cursor  Movement 


Forward-character 

Backward-character 

Forward-word 

Backward-word 

Forward-paragraph 

Backward-paragraph 

Beginning-of-line 

End-of-line 

Next-line 

Previous-line 

Next-page 

Previous-page 

Beginning-of-file 

End-of-file 

Scroll-one-line-up 

Scroll-one-line-down 

New  Line 

Newline-and-indent 

Newline-and-backup 

Newline 

Kill 

Kill-word 

Backward-kill-word 

Kill-selection 

Kill-to-end-of-line 

Kill-paragraph 

Kill-to-end-of-paragraph 


Delete 


Delete-next-character 

Delete-previous-character 

Delete-next-word 

Delete-previous-word 

Delete-selection 

Selection 

Insert-selection 

Select-word 

Select-all 

Select-start 

Select-adjust 

Select-end 

Extend-start 

Extend-adjust 

Extend-end 

Miscellaneous 

Redraw-display 

Insert-file 

Insert-char 

Display-caret 

Focus-in 

Focus-out 

Search 

Multiply 

Form-paragraph 

Transpose-characters 

No-op 


•  A  page  corresponds  to  the  size  of  the  Text  window.  For  example,  if  the  Text  window  is  50 
lines  in  length,  scrolling  forward  one  page  is  the  same  as  scrolling  forward  50  lines. 

•  The  delete  action  deletes  a  text  item.  The  kill  action  deletes  a  text  item  and  puts  the 
item  in  the  kill  buffer  (X  cut  buffer  1). 

•  The  insert-selection  action  retrieves  the  value  of  a  specified  X  selection  or  cut  buf 
fer,  with  fall-back  to  alternative  selections  or  cut  buffers. 

Cursor  Movement  Actions 

f orward-character (  ) 

backward-character (  ) 

These  actions  move  the  insert  point  forward  or  backward  one  character  in  the  buffer.  If 
the  insert  point  is  at  the  end  (or  beginning)  of  a  line,  this  action  moves  the  insert  point  to 
the  next  (or  previous)  line. 
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forward-word ( ) 
backward-word ( ) 

These  actions  move  the  insert  point  to  the  next  or  previous  word  boundary.   A  word 

boundary  is  defined  as  a  space,  a  tab,  or  a  carriage  return. 

forward-paragraph ( ) 

backward-paragraph ( ) 

These  actions  move  the  insert  point  to  the  next  or  previous  paragraph  boundary.  A  para 
graph  boundary  is  defined  as  two  carriage  returns  in  a  row  with  only  spaces  or  tabs 
between  them. 

beginning-of-line ( ) 
end-of-line ( ) 

These  actions  move  to  the  beginning  or  end  of  the  current  line.   If  the  insert  point  is 

already  at  the  end  or  beginning  of  the  line,  no  action  is  taken. 

next-line ( ) 

previous-line ( ) 

These  actions  move  the  insert  point  up  or  down  one  line.  If  the  insert  point  is  currently  n 
characters  from  the  beginning  of  the  line  then  it  will  be  n  characters  from  the  beginning 
of  the  next  or  previous  line.  If  n  is  past  the  end  of  the  line,  the  insert  point  is  placed  at 
the  end  of  the  line. 

next -page (  ) 

previous-page ( ) 

These  actions  move  the  insert  point  up  or  down  one  page  in  the  file.  One  page  is  defined 
as  the  current  height  of  the  text  widget  These  actions  always  place  the  insert  point  at  the 
first  character  of  the  top  line. 

beginning-of -f ile ( ) 
end-of-f ile ( ) 

These  actions  place  the  insert  point  at  the  beginning  or  end  of  the  current  text  buffer. 

The  text  widget  is  then  scrolled  the  minimum  amount  necessary  to  make  the  new  insert 

point  location  visible. 

scroll-one-line-up ( ) 

scroll-one-line-down ( ) 

These  actions  scroll  the  current  text  field  up  or  down  by  one  line.  They  do  not  move  the 
insert  point.  Other  than  the  scrollbars,  this  is  the  only  way  that  the  insert  point  may  be 
moved  off  of  the  visible  text  area.  The  widget  will  be  scrolled  so  that  the  insert  point  is 
back  on  the  screen  as  soon  as  some  other  action  is  executed. 

Delete  Actions 

delete-next-character ( ) 

delete-previous-character ( ) 

These  actions  remove  the  character  immediately  after  or  before  the  insert  point.  If  a  car 
riage  return  is  removed,  the  next  line  is  appended  to  the  end  of  the  current  line. 


X  Toolkit  Intrinsics  Reference  Manual  593 


Text  (continued)  Xt  -  Athena  Classes 

delete-next-word( ) 

delete-previous-word ( ) 

These  actions  remove  all  characters  between  the  insert  point  location  and  the  next  word 
boundary.  A  word  boundary  is  defined  as  a  space,  a  tab  or  a  carriage  return. 

delete-selection ( ) 

This  action  removes  all  characters  in  the  current  selection.  The  selection  can  be  set  with 
the  selection  actions. 

Selections  Actions 

select-word (  ) 

This  action  selects  the  word  in  which  the  insert  point  is  currently  located.  If  the  insert 
point  is  between  words,  it  will  select  the  previous  word. 

select-all (  ) 

This  action  selects  the  entire  text  buffer. 

select-start ( ) 

This  action  sets  the  insert  point  to  the  current  pointer  location,  where  a  selection  then 
begins.  If  many  of  these  selection  actions  occur  quickly  in  succession  then  the  selection 
count  mechanism  will  be  invoked. 

select-adjust ( ) 

This  action  allows  a  selection  started  with  the  select -start  action  to  be  modified,  as 
described  above. 

select-end (name [, name,  .  .  . ]) 

This  action  ends  a  text  selection  that  began  with  the  select-start  action,  and  asserts 
ownership  of  the  selection  or  selections  specified.  A  name  can  be  a  selection  (e.g.,  PRI 
MARY)  or  a  cut  buffer  (e.g.,  CUTJBUFFERO).  Note  that  case  is  important..  If  no  names  are 
specified,  PRIMARY  is  asserted. 

extend-start ( ) 

This  action  finds  the  nearest  end  of  the  current  selection,  and  moves  it  to  the  current 
pointer  location. 

extend-adjust ( ) 

This  action  allows  a  selection  started  with  an  extend-start  action  to  be  modified. 

extend-end ( name [, name,  .  .  . ]) 

This  action  ends  a  text  selection  that  began  with  the  extend-start  action,  and  asserts 
ownership  of  the  selection  or  selections  specified.  A  name  can  be  a  selection  (e.g.,  PRI 
MARY)  or  a  cut  buffer  (e.g.,  CUTJBUFFERO).  Note  that  case  is  important.  If  no  name  is 
given,  PRIMARY  is  asserted. 

insert-selection (name[, name,  .  .  .  ]) 

This  action  retrieves  the  value  of  the  first  (left-most)  named  selection  that  exists  or  the  cut 
buffer  that  is  not  empty.  This  action  then  inserts  it  into  the  Text  widget  at  the  current  insert 
point  location.  A  name  can  be  a  selection  (e.g.,  PRIMARY)  or  a  cut  buffer  (e.g.,  CUT_BUF- 
FERO).  Note  that  case  is  important. 
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New  Line  Actions 

newline-and-indent ( ) 

This  action  inserts  a  newline  into  the  text  and  adds  spaces  to  that  line  to  indent  it  to  match 
the  previous  line.  (Note:  this  action  still  has  a  few  bugs.) 

newline-and-backup ( ) 

This  action  inserts  a  newline  into  the  text  after  the  insert  point. 

newline (  ) 

This  action  inserts  a  newline  into  the  text  before  the  insert  point. 

Kill  Actions 

kill-word ( ) 

backward-kill-word ( ) 

These  actions  act  exactly  like  the  delete-next -word  and  delete-previous - 
word  actions,  but  they  store  the  word  that  was  killed  into  the  kill  buffer  (CUT_BUFFER_1). 

kill-selection (  ) 

This  action  deletes  the  current  selection  and  stores  the  deleted  text  into  the  kill  buffer 
(CUT_BUFFER_1). 

kill-to-end-of-line ( ) 

This  action  deletes  the  entire  line  to  the  right  of  the  insert  point,  and  stores  the  deleted  text 
into  the  kill  buffer  (CUT_BUFFER_1). 

kill-paragraph ( ) 

This  action  deletes  the  current  paragraph.  If  the  insert  point  is  between  paragraphs,  it 
deletes  the  paragraph  above  the  insert  point,  and  stores  the  deleted  text  into  the  kill  buffer 
(CUT_BUFFER_1). 

kill-to-end-of -paragraph ( ) 

This  action  deletes  everything  between  the  current  insert  point  and  the  next  paragraph 
boundary,  and  puts  the  deleted  text  into  the  kill  buffer  (CUT_BUFFER_1). 

Miscellaneous  Actions 

redraw-display ( ) 

This  action  recomputes  the  location  of  all  the  text  lines  on  the  display,  scrolls  the  text  to 
center  vertically  the  line  containing  the  insert  point  on  the  screen,  clears  the  entire  screen, 
and  then  redisplays  it 

insert-file ( [filename] ) 

This  action  activates  the  insert  file  popup.  The  filename  option  specifies  the  default 
filename  to  put  in  the  filename  buffer  of  the  popup.  If  no  filename  is  specified  the  buf 
fer  is  empty  at  startup. 

insert-char ( ) 

This  action  may  be  attached  only  to  a  key  event  It  calls  XLookupString  to  translate  the 
event  into  a  (rebindable)  Latin- 1  character  (sequence)  and  inserts  that  sequence  into  the 
text  at  the  insert  point  position. 
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insert-string (string[,  string,  .  .  .  ]) 

This  action  inserts  each  string  into  the  text  at  the  insert  point  location.  Any  string 
beginning  with  the  characters  "Ox"  and  containing  only  valid  hexadecimal  digits  in  the 
remainder  is  interpreted  as  a  hexadecimal  constant  and  the  corresponding  single  character 
is  inserted  instead. 

display-caret (state,  when) 

This  action  allows  the  insert  point  to  be  turned  on  and  off.  The  state  argument  specifies 
the  desired  state  of  the  insert  point.  This  value  may  be  any  of  the  string  values  accepted 
for  Boolean  resources  (e.g.,  on,  True,  off,  False,  etc.).  If  no  arguments  are  specified, 
the  default  value  is  True.  The  when  argument  specifies,  for  EnterNotify  or  Leave- 
Notify  events,  whether  or  not  the  focus  field  in  the  event  is  to  be  examined.  If  the  sec 
ond  argument  is  not  specified,  or  specified  as  something  other  than  always,  then  if  the 
action  is  bound  to  an  EnterNotify  or  LeaveNotify  event,  the  action  will  be  taken 
only  if  the  focus  field  is  True.  An  augmented  binding  that  might  be  useful  is: 

*Text . Translations :    #override   \ 

<FocusIn>:  display-caret (on)    \n\ 

<FocusOut>:         display-caret (of f) 

focus-in ( ) 
focus-out  (  ) 

These  actions  do  not  currently  do  anything. 

search (direction,  [string] ) 

This  action  activates  the  search  popup.  The  direction  must  be  specified  as  either  for 
ward  or  backward.  The  string  is  optional  and  is  used  as  an  initial  value  for  the  "Search 
for:"  string. 

multiply (value) 

The  multiply  action  allows  the  user  to  multiply  the  effects  of  many  of  the  text  actions. 
Thus  the  following  action  sequence: 

multiply (10)    delete-next-word () 

will  delete  10  words.  It  does  not  matter  whether  these  actions  take  place  in  one  event  or 
many  events.  Using  the  default  translations  the  key  sequence  Control-u,  Control-d  will 
delete  4  characters.  Multiply  actions  can  be  chained;  thus, 

multiply(5)    multiply(5) 

is  the  same  as 

multiply (25) 

If  the  string  reset  is  passed  to  the  multiply  action  the  effects  of  all  previous  multiplies 
are  removed  and  a  beep  is  sent  to  the  display. 

form-paragraph ( ) 

This  action  removes  all  the  carriage  returns  from  the  current  paragraph  and  reinserts  them 
so  that  each  line  is  as  long  as  possible,  while  still  fitting  on  the  current  screen.  Lines  are 
broken  at  word  boundaries  if  at  all  possible.  This  action  currently  works  only  on  Text 
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Text 


widgets  that  use  ASCII  text 

transpose-characters ( ) 

This  action  will  switch  the  positions  of  the  character  to  the  left  of  the  insert  point  and  the 
character  to  the  right  of  the  insert  point.  The  insert  point  will  then  be  advanced  one  char 
acter. 

no-op ( [action] ) 

The  no-op  action  makes  no  change  to  the  text  widget,  and  is  used  mainly  to  override  trans 
lations.  This  action  takes  one  optional  argument  If  this  argument  is  RingBell  then  a 
beep  is  sent  to  the  display. 

Event  Bindings 

The  default  event  bindings  for  the  Text  widget  are: 

char  defaultTextTranslations [ ]  =  "\ 


Ctrl<Key>F: 
Ctrl<Key>B: 
Ctrl<Key>D: 
Ctrl<Key>A: 
Ctrl<Key>E: 
CtrKKey>H: 
Ctrl<Key>J: 
CtrKKey>K: 
Ctrl<Key>L: 
Ctrl<Key>M: 
Ctrl<Key>N: 
CtrKKeyX): 
Ctrl<Key>P: 
CtrKKey>V: 
Ctrl<Key>W: 
CtrKKey>Y: 
CtrKKey>Z: 
Meta<Key>F: 
Meta<Key>B: 
Meta<Key>I: 
Meta<Key>K: 
Meta<Key>V: 
Meta<Key>Y: 
Meta<Key>Z: 
:Meta<Key>d: 
:Meta<Key>D: 
:Meta<Key>h: 
:Meta<Key>H: 
:Meta<Key>\< 
:Meta<Key>\> 
:Meta<Key>] : 
:Meta<Key>[ : 
"Shift  Meta<Key>Delete: 
Shift  Meta<Key>Delete: 


f orward-character ( )  \n\ 

backward-character!)  \n\ 

delete-next-character ( )  \n\ 

beginning-of-line ( )  \n\ 

end-of-line { )  \n\ 

delete-previous-character ( )  \n\ 

newline-and-indent (  )  \n\ 

kill-to-end-of-line( )  \n\ 

redraw-disp'lay  (  )  \n\ 

newline (  )  \n\ 

next-line ( )  \n\ 

newline-and-backup  (  )  \n\ 

previous-line!)  \n\ 

next-page ( )  \n\ 

kill-selection!)  \n\ 

unkill!)  \n\ 

scroll-one-line-up!)  \n\ 

forward-word ( )  \n\ 

backward-word!)  \n\ 

insert-file ( )  \n\ 

kill-to-end-of-paragraph ( )  \n\ 

previous-page ( )  \n\ 

stuff!)  \n\ 

scroll-one-line-down!)  \n\ 

delete-next-word ( )  \n\ 

kill-word!)  \n\ 

delete-previous-word!)  \n\ 

backward-kill-word!)  \n\ 

beginning-of-file ( )  \n\ 

end-of-file( )  \n\ 

forward-paragraph!)  \n\ 

backward-paragraph!)  \n\ 

delete-previous-word!)  \n\ 
backward-kill-word!)  \n\ 


'Shift  Meta<Key>Backspace:   delete-previous-word!)  \n\ 
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Shift  Meta<Key>Backspace  :   backward-kill-word  ()  \n\ 

<Key>Right :  f orward-character (  )  \n\ 

<Key>Left:  backward-character ()  \n\ 

<Key>Down:  next-line ()  \n\ 

<Key>Up :  previous-line ()  \n\ 

<Key>Delete:  delete-previous-character ()  \n\ 

<Key>BackSpace :  delete-previous-character ()  \n\ 

<Key>Linefeed:  newline-and-indent { )  \n\ 

<Key>Return:  newline (  )  \n\ 

<Key> :  insert-chart)  \n\ 

<FocusIn>:  f ocus-in (  )  \n\ 

<FocusOut>:  f ocus-out ( )  \n\ 

<BtnlDown>:  select-start ()  \n\ 

<BtnlMotion> :  extend-ad just ( )  \n\ 

<BtnlUp>:  extend-end (PRIMARY,  CUT_BUFFERO)  \n\ 

<Btn2Down>:  insert-selection (PRIMARY,  CUT_BUFFERO)  \n\ 

<Btn3Down>:  extend-start (  )  \n\ 

<Btn3Motion> :  extend-ad just ()  \n\ 

<Btn3Up>:  extend-end (PRIMARY,  CUT_BUFFERO) "; 

A  user-supplied  resource  entry  can  use  application-specific  bindings,  a  subset  of  the  supplied 
default  bindings,  or  both.  The  following  is  an  example  of  a  user-supplied  resource  entry  that 
uses  a  subset  of  the  default  bindings: 

Xmh*Text .Translations:  \ 

<Key>Right :  forward-character ( )  \n\ 

<Key>Left:  backward-character ()  \n\ 

Meta<Key>F :  forward-word ()  \n\ 

Meta<Key>B:  backward-word ()  \n\ 

:Meta<Key>] :  f orward-paragraph ( )  \n\ 

:Meta<Key>[:  backward-paragraph ()  \n\ 

<Key>:  insert-char () 

An  augmented  binding  that  is  useful  with  the  xclipboard  utility  is: 

*Text .Translations :  toverride  \ 

Buttonl  <Btn2Down>: extend-end (CLIPBOARD) 

The  Text  widget  fully  supports  the  X  selection  and  cut  buffer  mechanisms.  The  following 
actions  can  be  used  to  specify  button  bindings  that  will  cause  Text  to  assert  ownership  of  one  or 
more  selections,  to  store  the  selected  text  into  a  cut  buffer,  and  to  retrieve  the  value  of  a  selec 
tion  or  cut  buffer  and  insert  it  into  the  text  value. 

insert-selection(/ja/ne[,rjame, . . .  ]) 

Retrieves  the  value  of  the  first  (left-most)  named  selection  that  exists  or  the  cut 
buffer  that  is  not  empty  and  inserts  it  into  the  input  stream.  The  specified  name  can 
be  that  of  any  selection  (for  example,  PRIMARY  or  SECONDARY)  or  a  cut  buffer 
(i.e.,  CUT_BUFFERO  through  CUTJBUFFER7).  Note  that  case  matters. 

select-startQ 

Unselects  any  previously  selected  text  and  begins  selecting  new  text. 
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select -ad justQ 
extend-adjustQ 

Continues  selecting  text  from  the  previous  start  position. 

start-extendQ 

Begins  extending  the  selection  from  the  farthest  (left  or  right)  edge. 

select  -end(na/ne[,na/ne, . . .  ]) 

extend-end(/3a/ne[,/ja/ne, . . .  ]) 

Ends  the  text  selection,  asserts  ownership  of  the  specified  selection(s),  and  stores 
the  text  in  the  specified  cut  buffer(s).  The  specified  name  can  be  that  of  a  selection 
(for  example,  PRIMARY  or  SECONDARY)  or  a  cut  buffer  (i.e.,  CUT_BUFFERO 
through  CUT_BUFFER7).  Note  that  case  is  significant.  If  CUT_BUFFERO  is  listed, 
the  cut  buffers  are  rotated  before  storing  into  buffer  0. 

Programmatic  Interface 

A  Text  widget  lets  both  the  user  and  the  application  take  control  of  the  text  being  displayed. 
The  user  takes  control  with  the  scroll  bar  or  with  key  strokes  defined  by  the  event  bindings. 
The  scroll  bar  option  places  the  scroll  bar  on  the  left  side  of  the  window  and  can  be  used  with 
any  editing  mode.  The  application  takes  control  with  procedure  calls  to  the  Text  widget  to: 

•  Display  text  at  a  specified  position. 

•  Highlight  specified  text  areas. 

•  Replace  specified  text  areas. 

The  text  that  is  selected  within  a  Text  window  may  be  assigned  to  an  X  selection  or  copied  into 
a  cut  buffer  and  can  be  retrieved  by  the  application  with  the  Intrinsics  xtGetSelection- 
Value  or  the  Xlib  XFetchBytes  functions,  respectively.  Several  standard  selection 
schemes  (e.g.,  character/word/paragraph  with  multiclick)  are  supported  through  the  event  bind 
ings. 

To  create  a  Text  widget,  use  xtCreateWidget  and  specify  the  class  variable  ascii- 
TextWidgetClass. 

If  you  want  to  create  an  instance  of  the  class  textwidgetciass,  you  must  provide  a 
source  and  a  sink  when  the  widget  is  created.  The  Text  widget  cannot  be  instantiated 
without  both. 

•  To  enable  an  application  to  select  a  piece  of  text,  use  XawText  Set  Select  ion: 

void  XawTextSetSelection(w,    left,    right) 
Widget    w; 
XawTextPosition   left,    right; 

where: 

w  Specifies  the  window  ID. 

left  Specifies  the  character  position  at  which  the  selection  begins. 
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right  Specifies  the  character  position  at  which  the  selection  ends. 

If  redisplay  is  enabled,  this  function  highlights  the  text  and  makes  it  the  PRIMARY  selec 
tion.  This  function  does  not  have  any  effect  on  CUT_BUFFERO. 

To  unhighlight  previously  highlighted  text  in  a  window,  use  XawTextUnset- 
Selection: 

void   XawTextUnsetSelection ( w) 
Widget    w; 

where  w  specifies  the  window  ID. 

•       To  enable  the  application  to  get  the  character  positions  of  the  selected  text,  use  Xaw- 
TextGet Select ionPos: 

void  XawTextGetSelectionPos ( w,  begin_return,  end_return) 
Widget  w; 
XawTextPosition  *begin_return,  *end_return; 

where: 

w  Specifies  the  window  ID. 

begin_ret urn 

Specifies  a  pointer  to  the  location  to  which  the  beginning  character 
position  of  the  selection  is  returned. 

end_return     Specifies  a  pointer  to  the  location  to  which  the  ending  character 
position  of  the  selection  is  returned. 

If  the  returned  values  are  equal,  there  is  no  current  selection. 

To  enable  an  application  to  replace  text,  use  XawTextReplace: 

int   XawTextReplace (w,    start_pos,    endjpos,    text) 
Widget    w; 

XawTextPosition    start_posr    end_pos; 
XawTextBlock    *text; 

where: 

w  Specifies  the  window  ID. 

start_pos  Specifies  the  starting  character  position  of  the  text  replacement. 

end_pos  Specifies  the  ending  character  position  of  the  text  replacement. 

text  Specifies  the  text  to  be  inserted  into  the  file.  This  function  cannot 

replace  text  in  read-only  Text  widgets,  and  it  can  only  append  text 
to  an  append-only  Text  widget 

The  XawTextReplace  function  deletes  text  in  the  specified  range  (startPos,  end- 
Pos)  and  inserts  the  new  text  at  start_pos.  The  return  value  is  XawEditDone  if  the 
replacement  is  successful,  XawPositionError  if  the  edit  mode  is  XawtextAppend 
and  start_pos  is  not  the  last  character  of  the  source,  or  XawEditError  if  either  the 
source  was  read-only  or  the  range  to  be  deleted  is  larger  than  the  length  of  the  source. 
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The  XawTextBlock  structure  (defined  in  <Xll/Xaw/Text.h>)  contains: 

typedef  struct  { 

int  firstPos; 

int  length; 

char  *ptr; 

Atom  format; 
}  XawTextBlock,  *TextBlockPtr; 

The  firstPos  field  is  the  starting  point  to  use  within  the  ptr  field.  The  value  is  usually 
zero.  The  length  field  is  the  number  of  characters  that  are  transferred  from  the  ptr 
field.  The  number  of  characters  transferred  is  usually  the  number  of  characters  in  ptr, 
which  is  the  string  to  insert  into  the  Text  widget.  The  format  field  is  not  currently  used, 
but  should  be  specified  as  FMT8BIT.  The  XawTextReplace  arguments  start_pos 
and  end__pos  represent  the  text  source  character  positions  for  the  existing  text  that  is  to 
be  replaced  by  the  text  in  the  XawTextBlock  structure.  The  characters  from 
start_pos  up  to  but  not  including  end_pos  are  deleted,  and  the  characters  that  are 
specified  by  the  text  block  are  inserted  in  their  place.  If  start_pos  and  end_pos  are 
equal,  no  text  is  deleted  and  the  new  text  is  inserted  after  start_pos. 

Only  Latin- 1  text  is  currently  supported,  and  only  one  font  can  be  used  for  each  Text 
widget. 

To  search  for  a  string  in  the  Text  widget,  use  XawText  Search: 

XawTextPosition   XawTextSearch ( wr    dir,    text) 
Widget    w; 

XawTextScanDirection    dir; 
XawTextBlock    *    text; 

where: 

w  Specifies  the  window  ID. 

dir  Specifies  the  direction  to  search  in.  Legal  values  are  XawsdLef  t 

and  XawsdRight. 

text  Specifies  a  text  block  structure  (see  XawTextReplace  for  the 

definition)  that  contains  the  text  to  search  for. 

The  XawTextSearch  function  will  begin  at  the  insert  point  location  and  search  in  the  direc 
tion  specified  for  a  string  that  matches  the  one  passed  in  text.  If  the  string  is  found,  the  loca 
tion  of  the  first  character  in  the  string  is  returned.  If  the  string  could  not  be  found,  then  the 
value  XawTextSearchError  is  returned. 

•       To  redisplay  a  range  of  characters,  use  XawText  Invalidate: 

void   XawText Invalidate (w,    from,    to) 
Widget    w; 
XawTextPosition    from,    to; 

where: 
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w  Specifies  the  window  ID. 

from  Specifies  the  starting  character  to  be  displayed. 

t  o  Specifies  the  last  character  to  be  displayed. 

The  XawText Invalidate  function  causes  the  specified  range  of  characters  to  be 
redisplayed  immediately  if  redisplay  is  enabled,  or  the  next  time  that  redisplay  is  enabled. 

To  enable  redisplay,  use  XawTextEnableRedisplay: 

void  XawTextEnableRedisplay (w) 
Widget    w; 

where  w  specifies  the  window  ID.  The  XawTextEnableRedisplay  function  flushes 
any  changes  due  to  batched  updates  when  XawTextDisableRedi splay  was  called 
and  allows  future  changes  to  be  reflected  immediately. 

To  disable  redisplay  while  making  several  changes,  use  XawTextDisableRedi  splay: 

void   XawTextDisableRedisplay (w) 
Widget    w; 

where  w  specifies  the  window  ID. 

The  XawTextDisableRedisplay  function  causes  all  changes  to  be  batched  until 
XawTextDisplay  or  XawTextEnableRedisplay  is  called. 

•       To  display  batched  updates,  use  XawTextDisplay: 

void  XawTextDisplay (w) 
Widget  w; 

where  w  specifies  the  window  ID. 

The  XawTextDisplay  function  forces  any  accumulated  updates  to  be  displayed. 

The  following  procedures  are  convenience  procedures  that  replace  calls  to  xtSetValues  or 
xtGetValues  when  only  a  single  resource  is  to  be  modified  or  retrieved. 

To  obtain  the  character  position  of  the  leftmost  character  on  the  first  line  displayed  in  the 
widget  (that  is,  the  value  of  XtNdisplayPosition),  use  XawTextTopPosition. 

XawTextPosition  XawTextTopPosition (w) 
Widget  w; 

where  w  specifies  the  Text  widget 

To  assign  a  new  selection  array  to  a  text  widget  use  XawTextSetSelectionArray: 

void  XawTextSetSelectionArray (w,    sarray) 
Widget    w; 
XawTextSelectType   *    sarray; 

w  Specifies  the  Text  widget 

sarray  Specifies  a  selection  array. 
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Calling  this  function  is  equivalent  to  setting  the  value  of  the  xtNselectionTypes 
resource. 

To  move  the  insertion   caret  to  the  specified   source  position,   use  XawTextSet- 
InsertionPoint: 

void   XawTextSetlnsertionPoint (w,    position) 
Widget    w; 
XawTextPosition  position; 

where: 

w  Specifies  the  Text  widget 

position         Specifies  the  position  to  which  to  move  the  insertion  caret. 

The  text  will  be  scrolled  vertically,  if  necessary,  to  make  the  line  containing  the  insertion 
point  visible.  The  result  is  equivalent  to  setting  the  xtNinsertPosition  resource. 

•  To  obtain  the  current  position  of  the  insertion  caret,  use  XawTextGetlnsertion- 
Point: 

XawTextPosition  XawTextGetlnsertionPoint (w) 
Widget    w; 

where  w  specifies  the  Text  widget 

The  result  is  equivalent  to  retrieving  the  value  of  the  XtNinsertPosition  resource. 

•  To  replace  the  text  source  in  the  specified  widget,  use  XawTextSetSource: 

void  XawTextSetSource (w,    source,    position) 
Widget    w; 
Widget    source; 
XawTextPosition  position; 

where: 

w  Specifies  the  Text  widget 

source  Specifies  the  source  widget 

posi  tion         Specifies  the  location  to  place  the  replacement  text 

A  display  update  will  be  performed  if  redisplay  has  not  been  disabled, 

•  To  obtain  the  current  text  source  for  the  specified  widget,  use  XawTextGet  Source: 

XawTextSource   XawTextGetSource ( w) 
Widget    w; 

where  w  specifies  the  Text  widget 

•  To  enable  and  disable  the  insert  point,  use  XawTextDisplayCaret: 

void  XawTextDisplayCaret (w,    visible) 
Widget    w; 
Boolean    visible; 
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w  Specifies  the  Text  widget 

vi  sibl  e  Specifies  whether  caret  should  be  displayed. 

If  visible  is  False,  the  insert  point  will  be  disabled.  The  marker  can  be 
re-enabled  either  by  setting  visible  to  True,  by  calling  xtSetValues, 
or  by  executing  the  display-caret  action  routine. 

Creating  Sources  and  Sinks 

The  following  functions  for  creating  and  destroying  text  sources  and  sinks  are  called  automati 
cally  by  as ciiText Class,  and  it  is  therefore  necessary  for  the  client  to  use  them  only  when 
creating  an  instance  of  textwidgetClass. 

•  To  create  a  new  ASCII  text  sink,  use  XtCreateWidget  and  specify  the  class  variable 
asciiSinkOb  jectClass.  The  resources  required  by  the  sink  are  qualified  by  the  name 
and  class  of  the  parent  and  the  sub-part  name  xtNtextSink  and  class  xtCText  Sink. 

•  To  deallocate  an  ASCII  text  sink,  use  xtDestroyWidget  and  specify  the  widget  of  the 
AsciiSink  widget  The  sink  must  not  be  in  use  by  any  widget  or  an  error  will  result. 

•  To  create  a  new  text  source,  use  XtCreateWidget  and  specify  the  class  variable 
asciiSourceOb  jectClass.  The  resources  required  by  the  source  are  qualified  by  the 
name  and  class  of  the  parent  and  the  sub-part  name  Xt Nt ex t Source  and  class  xt- 

CTextSource. 

•  To  deallocate  a  text  disk  source,  use  XtDestroyWidget  and  specify  the  widget  of  the 
AsciiSource  widget.  The  sink  must  not  be  in  use  by  any  widget  or  an  error  will  result. 
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Name 

Toggle  widget  —  button  that  maintains  a  Boolean  state. 

Synopsis 

tinclude  <Xll/StringDefs.h> 

#include  <Xll/Intrinsic.h> 

#include  <Xll/Xaw/Toggle .h> 

widget  =  XtCreateWidget (name,  toggleWidgetClass, 


Class  Hierarchy 

Core  — >  Simple 


Label  ->  Command  — >  Toggle 


Description 

The  Toggle  widget  is  an  area,  often  rectangular,  containing  a  text  or  pixmap  label.  This  widget 
maintains  a  Boolean  state  (e.g.  True/False  or  On/Off)  and  changes  state  whenever  it  is  selected. 
When  the  pointer  is  on  the  button,  the  button  border  is  highlighted  to  indicate  that  the  button  is 
ready  for  selection.  When  pointer  button  1  is  pressed  and  released,  the  Toggle  widget  indicates 
that  it  has  changed  state  by  reversing  its  foreground  and  background  colors,  and  its  notify 
action  is  invoked,  calling  all  functions  on  its  callback  list.  If  the  pointer  is  moved  out  of  the 
widget  before  the  button  is  released,  the  widget  reverts  to  its  normal  foreground  and  back 
ground  colors,  and  releasing  the  button  has  no  effect.  This  behavior  allows  the  user  to  cancel 
an  action. 

Toggle  buttons  may  also  be  part  of  a  radio  group.  A  radio  group  is  a  list  of  Toggle  buttons  in 
which  no  more  than  one  Toggle  may  be  set  at  any  time.  A  radio  group  is  identified  by  the 
widget  ID  of  any  one  of  its  members.  The  convenience  routine  XawToggleGetCurrent 
returns  information  about  the  currently  set  Toggle  button  in  the  radio  group. 

Resources 

When  creating  a  Toggle  widget  instance,  the  following  resources  are  retrieved  from  the  argu 
ment  list  or  from  the  resource  database: 


Name 

Type 

Default 

Description 

XtNaccelerators 

AcceleratorTable 

NULL 

List  of  event-to-action  bindings  to  be 
executed  by  this  widget,  even  though 
the  event  occurred  in  another  widget 

XtNancestor- 
Sensitive 

Boolean 

True 

Sensitivity  state  of  the  ancestors  of  this 
widget.     A    widget   is    insensitive   if 
either  it  or  any  of  its  ancestors  is  insen 

sitive 

XtNbackground 

Pixel 

XtDefault- 
Background 

Window  background  color 

XtNbackground- 
Pixmap 

Pixmap 

XtUnspecified- 
Pixmap 

Window  background  pixmap 

XtNbitmap 

Pixmap 

None 

Pixmap  to  display  in  place  of  the  label 

XtNborderColor 

Pixel 

XtDefault- 

Window  border  color 

Foreground 
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Name 

Type 

Default 

Description 

XtNborderP  ixmap 

P  ixmap 

XtUnspecified- 

Window  border  pixmap 

Pixmap 

XtNborderWidth 

Dimension 

1 

Width  of  button  border 

XtNcallback 

XtCallbackList 

NULL 

Callback  for  button  select 

XtNcolormap 

Colormap 

Parent's  colormap 

Colormap  that  this  widget  will  use 

XtNcornerRound- 

Percent 

Dimension 

25 

See  below 

XtNcursor 

Cursor 

None 

Pointer  cursor 

XtNdepth 

int 

Parent's  depth 

Depth  of  this  widget's  window 

XtNdestroy- 

XtCallbackList 

NULL 

Callbacks  forXtDestroyWidget 

Callback 

XtNfont 

XFont  Struct* 

XtDefaultFont 

Label  font 

XtNforeground 

Pixel 

XtDefault- 

Foreground  color 

Foreground 

XtNheight 

Dimension 

font  height  +  2  * 

Button  height 

XtNinternalHeight 

XtNhighlight- 

Dimension 

2 

Width  of  border  to  be  highlighted 

Thickness 

XtNinsensitive- 

P  ixmap 

GrayPixmap 

Border  when  not  sensitive 

Border 

XtNinternal- 

Dimension 

2 

Internal  border  height  for  highlighting 

Height 

XtNinternalWidth 

Dimension 

4 

Internal  border  width  for  highlighting 

XtNjustify 

Xt  Justify 

XtJustifyCenter 

Type  of  text  alignment 

XtNlabel 

String 

name  of  widget 

Button  label 

XtNmappedWhen- 

Boolean 

TRUE 

Whether  XtMapWidget  is  automatic 

Managed 

t 

XtNradioData 

Pointer 

Name  of  widget 

See  below 

XtNradioGroup 

Widget 

No  radio  group 

See  below 

XtNresize 

Boolean 

TRUE 

Whether  to  auto-resize  in  SetValues 

XtNscreen 

Screen 

Parent's  screen 

Screen    on    which    this    widget    is 

displayed.     This    is    not    a    sellable 

resource 

XtNsensitive 

Boolean 

TRUE 

Whether  widget  receives  input 

XtNshapeStyle 

ShapeStyle 

Rectangle 

Type  of  nonrectangular  button 

XtNstate 

Boolean 

Off 

See  below 

XtNtranslations 

Translation- 

See  below 

Event-to-action  translations 

Table 

XtNwidth 

Dimension 

XtNlabel  width+2* 

Button  width 

XtNinternalWidth 

XtNx 

Position 

0 

x-coordinate  in  pixels 

XtNy 

Position 

0 

y  -coordinate  in  pixels 
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Note  that: 

1.  The  Toggle  widget  supports  two  callback  lists:    xtNdestroyCallback  and  xt- 
Ncallback.  The  notify  action  executes  the  callbacks  on  the  xtNcallback  list. 
The  call_data  argument  is  unused. 

2.  When  a  bitmap  of  depth  greater  that  1  is  specified,  the  set,  unset,  and  reset  actions 
have  no  effect,  since  no  foreground  and  background  colors  are  used  in  a  multi-plane  pix- 
map. 

The  new  resources  (not  inherited  from  superclasses)  associated  with  the  Toggle  widget  are: 

XtNradioData 

Specifies  the  data  that  is  returned  by  XawToggleGetCurrent  when  this  is  the  currently 
set  widget  in  the  radio  group.  This  value  is  also  used  to  identify  the  Toggle  that  is  set  by  a 
call  to  XawToggleSetCurrent.  XawToggleGetCurrent  returns  NULL  if  no  widget 
in  a  radio  group  is  currently  set.  Programmers  must  not  specify  NULL  (or  0)  as  xt- 
NradioData. 

XtNradioGroup 

Specifies  another  Toggle  widget  that  is  in  the  radio  group  to  which  this  Toggle  widget 
should  be  added.  A  radio  group  is  a  group  of  Toggle  widgets,  only  one  of  which  may  be 
set  at  a  time.  If  this  value  is  NULL  (the  default),  then  the  Toggle  is  not  part  of  any  radio 
group  and  can  change  state  without  affecting  any  other  Toggle  widgets.  If  the  widget 
specified  in  this  resource  is  not  already  in  a  radio  group,  then  a  new  radio  group  is  created 
containing  these  two  Toggle  widgets.  No  Toggle  widget  can  be  in  multiple  radio  groups. 

XtNstate 

Specifies  whether  the  Toggle  widget  is  set  (True)  or  unset  (False). 

Translations  and  Actions 

The  following  default  translation  bindings  are  used  by  the  Toggle  widget: 

<EnterWindow> : highlight (Always) 
<LeaveWindow> runhighlight ( ) 
<BtnlDown>, <BtnlUp> : toggle ( )  notify (  ) 

The  Toggle  widget  supports  the  following  actions: 

•  Switching  the  button  between  the  foreground  and  background  colors  with  set,  unset 
and  toggle. 

•  Processing  application  callbacks  with  notify. 

Switching  the  internal  border  between  highlighted  and  unhighlighted  states  with  high 
light  and  unhighlight. 

The  actions  supported  by  Toggle  are  listed  below: 

highlight  (condition) 

Displays  the  internal  highlight  border  in  the  color  (xtNf  oreground  or 
xtNbackground)  that  contrasts  with  the  interior  color  of  the  Toggle 
widget  The  conditions  WhenUnset  and  Always  are  understood  by  this 
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unhighlightQ 
set() 

unsetQ 
toggle() 


resetQ 


notify() 


action  procedure.  If  no  argument  is  passed,  WhenUnset  is  assumed. 

Displays  the  internal  highlight  border  in  the  color  (xtNf  oreground  or 
xtNbackground)  that  matches  the  interior  color  of  the  Toggle  widget. 

Enters  the  set  state,  in  which  notify  is  possible,  and  displays  the  interior 
of  the  button  in  the  foreground  color.  The  label  or  pixmap  is  displayed  in 
the  background  color. 

Cancels  the  set  state  and  displays  the  interior  of  the  button,  including  the 
highlight  border,  in  the  background  color.  The  label  or  pixmap  is 
displayed  in  the  foreground  color. 

Changes  the  current  state  of  the  Toggle  widget,  setting  the  widget  if  it  was 
previously  unset,  and  unsetting  it  if  it  was  previously  set.  If  the  widget  is 
to  be  set  and  is  in  a  radio  group,  then  this  action  procedure  may  unset 
another  Toggle  widget,  causing  all  routines  on  its  callback  list  to  be 
invoked.  The  callback  routines  for  the  Toggle  to  be  unset  are  called 
before  those  for  the  Toggle  to  be  set. 

Cancels  any  set  or  highlight  action  and  displays  the  interior  of  the 
button  in  the  background  color,  with  the  label  displayed  in  the  foreground 
color. 

When  the  button  is  set,  this  action  calls  all  functions  in  the  callback  list 
named  by  the  xtNcallback  resource.  The  value  of  the  call_data 
argument  in  these  callback  functions  is  undefined. 


Radio  Groups 

Two  types  of  radio  groups  are  typically  desired  by  applications.  In  the  first  type,  the  default 
translations  for  the  Toggle  widget  implement  a  "zero,  or  one  of  many"  radio  group.  This  means 
that  no  more  than  one  button  can  be  active,  but  no  buttons  need  to  be  active. 

The  other  type  of  radio  group  is  "one  of  many"  and  has  the  more  restricted  policy  that  exactly 
one  radio  button  will  always  be  active.  Toggle  widgets  can  be  used  to  provide  this  interface  by 
modifying  the  translation  table  of  each  Toggle  in  the  group: 

<EnterWindow> : highlight (Always) 
<LeaveWindow>:unhighlight ( ) 
<BtnlDown>, <BtnlUp> : set ( )  notify ( ) 

This  translation  table  does  not  allow  any  Toggle  to  be  unset  unless  another  Toggle  has  been  set. 
The  application  programmer  must  choose  an  initial  state  for  the  radio  group  by  setting  the  xt- 
Nstate  resource  of  one  of  its  member  widgets  to  True. 

Programmatic  Interface 

The  following  functions  allow  easy  access  to  the  Toggle  widget's  radio  group  functionality. 

•  To  allow  an  application  to  either  change  the  Toggle's  radio  group,  add  the  Toggle  to  a 
radio  group,  or  remove  the  Toggle  from  a  radio  group,  use  XawToggleChangeRadio- 
Group. 
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void   XawToggleChangeRadioGroup(w,    radio_group) 
Widget    w,    radio_group; 

where: 

w  Specifies  the  widget  ID. 

radio_group  Specifies  the  widget  ID  of  Toggle  in  the  new  radio  group.  If  NULL, 
then  the  Toggle  is  removed  from  any  radio  group  of  which  it  is  a 
member. 

If  a  Toggle  is  already  set  in  the  new  radio  group,  and  if  the  Toggle  to  be  added  is  also  set, 
then  the  previously  set  Toggle  in  the  radio  group  is  unset  and  its  callback  procedures  are 
invoked. 

To  find  the  currently  selected  Toggle  in  a  radio  group  of  Toggle  widgets,  use  Xaw- 
ToggleGetCurrent: 

caddr_t   XawToggleGetCurrent (radio_group) ; 
Widget    radio_group; 

where  radio_ group  specifies  the  widget  ID  of  any  Toggle  widget  in  the  radio  group. 

The  value  returned  by  this  function  is  the  radioData  of  the  Toggle  in  this  radio  group 
that  is  currently  set  The  default  value  for  radioData  is  the  name  of  that  Toggle  widget. 
If  no  Toggle  is  set  in  the  radio  group  specified,  then  NULL  is  returned. 

•  To  change  the  Toggle  that  is  currently  set  in  a  radio  group,  use  XawToggleSet- 
Current: 

void   XawToggleSetCurrent (radio_group,    radio_data)  ; 
Widget    radio_group; 
caddr_t   radio_data; 

where: 

radio_group  Specifies  any  Toggle  widget  in  the  radio  group. 

radio_data  Specifies  the  radioData  identifying  the  Toggle  that  should  be  set 
in  the  radio  group  specified  by  the  radio_ group  argument. 

XawToggleSetCurrent  locates  the  Toggle  widget  to  be  set  by  matching 
radio_data  against  the  radioData  for  each  Toggle  in  the  radio  group.  If  none 
match,  XawToggleSetCurrent  returns  without  making  any  changes.  If  more  than  one 
Toggle  matches,  XawToggleSetCurrent  arbitrarily  chooses  a  Toggle  to  set.  If  this 
changes  the  state  of  any  Toggle  widgets,  all  routines  in  their  callback  lists  will  be  invoked. 
The  callback  routines  for  a  Toggle  to  be  unset  are  called  before  those  for  the  Toggle  to  be 
set 

•  To  unset  all  Toggle  widgets  in  a  radio  group,  use  XawToggleUnsetCurrent: 

void  XawToggleUnsetCurrent (radio_group) ; 
Widget   radio_group; 

where  radio_group  specifies  any  Toggle  widget  in  the  radio  group. 
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If  this  changes  the  state  of  a  Toggle  widget,  all  routines  on  its  callback  list  will  be  invoked. 

•       To  create  a  Toggle  widget  instance,  use  xtCreateWidget  and  specify  the  class  variable 

toggleWidgetClass. 

To  destroy  a  Toggle  widget  instance,  use  xtDestroyWidget  and  specify  the  widget  ID 
of  the  Toggle  widget 

See  Also 

Command(5),  Label(5),  MenuButton(5). 
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Name 

Viewport  widget  —  scrollable  viewing  area  widget. 


Synopsis 

tinclude 
#include 
tinclude 
widget  = 


<Xll/StringDefs.h> 

<X1 1 /Intrinsi c . h> 

<X1 1  /Xa w/Viewport . h>fP 

Xt  Create  Widget  (name,    viewportWidgetClass, 


Class  Hierarchy 

Core  — >  Constraint  — »  Form  — >  Viewport 

Description 

The  Viewport  widget  consists  of  a  frame  window,  one  or  two  Scrollbars,  and  an  inner  window 
(usually  containing  a  child  widget).  The  size  of  the  frame  window  is  determined  by  the  view 
ing  size  of  the  data  that  is  to  be  displayed  and  the  dimensions  to  which  the  Viewport  is  created. 
The  inner  window  is  the  full  size  of  the  data  that  is  to  be  displayed  and  is  clipped  by  the  frame 
window.  The  Viewport  widget  controls  the  scrolling  of  the  data  directly.  No  application  call 
backs  are  required  for  scrolling. 

When  the  geometry  of  the  frame  window  is  equal  in  size  to  the  inner  window,  or  when  the  data 
does  not  require  scrolling,  the  Viewport  widget  automatically  removes  any  scroll  bars.  The 
f  orceBars  option  causes  the  Viewport  widget  to  display  any  scroll  bar  permanently. 

Resources 

When  creating  a  Viewport  widget  instance,  the  following  resources  are  retrieved  from  the  argu 
ment  list  or  from  the  resource  database: 


Name 

Type 

Default 

Description 

XtNaccelerators 

AcceleratorTable 

NULL 

list  of  event-to-action  bindings  to  be  exe 
cuted  by  this  widget,  even  though  the  event 
occurred  in  another  widget 

XtNancestor- 
Sensitive 

Boolean 

True 

Sensitivity  state  of  the  ancestors  of  this 
widget:  a  widget  is  insensitive  if  either  it  or 
any  of  its  ancestors  is  insensitive 

XtNallowHoriz 

Boolean 

FALSE 

Flag  to  allow  horizontal  scroll  bars 

XtNallowVert 

Boolean 

FALSE 

Flag  to  allow  vertical  scroll  bars 

XtNbackground 

Pixel 

XtDefault- 
Background 

Window  background  color 

XtNbackground- 
Pixmap 

Pixmap 

XtUnspecified- 
Pixmap 

Window  background  pixmap 

XtNborderColor 

Pixel 

XtDefault- 

Window  border  color 

Foreground 

XtNborderPixmap 

Pixmap 

XtUnspecified- 
Pixmap 

Window  border  pixmap 

XtNborderWidth 

Dimension 

1 

Width  of  the  border  in  pixels 

X  Toolkit  Intrinsics  Reference  Manual 


611 


Viewport 


(continued) 


Xt  -  Athena  Classes 


Name 

Type 

Default 

Description 

XtNchildren 

WidgetList 

NULL 

List  of  all  current  children  of  this  composite 
widget 

XtNcolormap 

Colormap 

Parent's  colormap 

Colormap  that  this  widget  will  use 

XtNdepth 

int 

Parent's  depth 

Depth  of  this  widget's  window 

XtNdestroy- 

XtCallbackList 

NULL 

Callback  forXtDestroyWidget 

Callback 

XtNforceBars 

Boolean 

FALSE 

Flag  to  force  display  of  scroll  bars 

XtNheight 

Dimension 

height  of 
child 

Height  of  the  widget 

XtNmappedWhen- 

Boolean 

TRUE 

Whether  XtMapWidget  is  automatic 

Managed 

XtNnumChildren 

Cardinal 

0 

Number  of  children  in  this  composite  widget 

XtNscreen 

Screen 

Parent's  screen 

Screen  on  which  this  widget  is  displayed 

XtNsensitive 

Boolean 

TRUE 

Whether  widget  should  receive  input 

XtNtranslations 

Trans  1  at  ionTable 

NULL 

Event-to-action  translations 

XtNuseBottom 

Boolean 

FALSE 

Flag  to  indicate  bottomAop  bars 

XtNuseRight 

Boolean 

FALSE 

Flag  to  indicate  right/left  bars 

XtNwidth 

Dimension 

width  of 
child 

Width  of  the  widget 

XtNx 

Position 

0 

x  coordinate  in  pixels 

XtNy 

Position 

0 

y  coordinate  in  pixels 

The  Viewport  widget  manages  a  single  child  widget  When  the  size  of  the  child  is  larger  than 
the  size  of  the  Viewport,  the  user  can  interactively  move  the  child  within  the  Viewport  by  repo 
sitioning  the  scroll  bars. 

The  default  size  of  the  Viewport  before  it  is  realized  is  the  width  and/or  height  of  the  child. 
After  it  is  realized,  the  Viewport  will  allow  its  child  to  grow  vertically  or  horizontally  if  xt- 
NallowVert  or  xtNallowHoriz,  respectively,  were  set  If  the  corresponding  vertical  or 
horizontal  scrollbar  is  not  enabled,  the  Viewport  will  propagate  the  geometry  request  to  its  own 
parent  and  the  child  will  be  allowed  to  change  size  only  if  the  (grand)  parent  allows  it  Regard 
less  of  whether  or  not  scrollbars  are  enabled  in  the  corresponding  direction,  if  the  child  requests 
a  new  size  smaller  than  the  Viewport  size,  the  change  will  be  allowed  only  if  the  parent  of  the 
Viewport  allows  the  Viewport  to  shrink  to  the  appropriate  dimension. 

The  scrollbar  children  of  the  Viewport  are  named  horizontal  and  vertical.  By  using 

these  names  the  programmer  can  specify  resources  for  the  individual  scrollbars.  xtSet- 

Values  can  be  used  to  modify  the  resources  dynamically  once  the  widget  ID  has  been 
obtained  with  XtNameToWidget. 

Note  that  although  the  Viewport  is  a  subclass  of  the  Form,  no  resources  for  the  Form  my  be 
supplied  for  any  of  the  children  of  the  Viewport  These  constraints  are  managed  internally,  and 
are  not  meant  for  public  consumption. 


612 


X  Toolkit  Intrinsics  Reference  Manual 


Xt  -  Athena  Classes  (continued)  Viewport 

Programmatic  Interface 

To  create  a  Viewport  widget  instance,  use  xtCreateWidget  and  specify  the  class  vari 
able  viewportWidgetClass. 

•  To  insert  a  child  into  a  Viewport  widget,  use  XtCreateWidget  and  specify  as  the  par 
ent  the  widget  ID  of  the  previously  created  Viewport  as  the  parent. 

•  To  remove  a  child  from  a  Viewport  widget,  use  xtUnmanageChild  or  xtDestroy- 
widget  and  specify  the  widget  ID  of  the  child. 

•  To  delete  the  inner  window,  any  children,  and  the  frame  window,  use  xtDestroy- 
widget  and  specify  the  widget  ID  of  the  Viewport  widget. 

See  Also 

Scrollbar 
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Function  Summaries 


This  quick  reference  is  intended  to  help  you  find  and  use  the  right  function  or  prototype  for  a 
particular  task.  It  organizes  the  Section  1  and  Section  2  reference  pages  into  two  lists: 

•  Listing  of  functions,  macros,  and  prototype  procedures  by  groups. 

•  Alphabetical  listing  of  functions,  macros,  and  prototype  procedures. 

All  routines  listed  below  start  with  Xt.  To  improve  readability,  this  prefix  has  been  left  off  of 
the  names  in  the  first  column.  The  first  column  also  indicates  which  section  to  find  the  rou 
tines  in.  If  the  name  is  followed  by  a  (2),  the  routine  can  be  found  in  Section  2;  otherwise, 
the  routine  can  be  found  in  Section  1 . 


Group  Listing  with  Brief  Descriptions 


Application  Contexts 

CreateApplicationContext 
Destroy  ApplicationContext 
Displaylnitialize 
GetApplicationNameAndClass 

OpenDisplay 

Toolkitlnitialize 

WidgetToApplicationContext 

Argument  Lists 

Number 
SetArg 

Callbacks 

AddCallback 
AddCallbacks 
CallbackProc(2) 
CallCallbackList 


Create  an  application  context. 

Destroy  an  application  context  and  close  its  displays. 

Initialize  a  display  and  add  it  to  an  application  context. 

Return  the  application  name  and  class  as  passed  to  XtDisplay- 

Initialize  for  a  particular  Display. 

Open,  initialize,  and  add  a  display  to  an  application  context. 

Initialize  the  X  Toolkit  internals. 

Get  the  application  context  for  a  given  widget. 


Determine  the  number  of  elements  in  a  fixed-size  array. 
Modify  an  argument  list  dynamically. 


Add  a  callback  procedure  to  a  widget's  callback  resource. 

Add  a  list  of  callback  procedures  to  a  given  widget's  callback  list. 

Prototype  callback  procedure. 

Execute  the  procedures  in  a  callback  list,  specifying  the  callback  list 

by  address. 
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CallCallbacks 

HasCallbacks 

RemoveAllCallbacks 

RemoveCallback 

RemoveCallbacks 

Error  Handling 

AppError 

AppErrorMsg 

AppGetErrorDatabase 

AppGetErrorDatabaseText 

AppSetErrorHandler 

AppSetErrorMsgHandler 

AppSetWamingHandler 

AppSetWamingMsgHandler 

AppWarning 

AppWarningMsg 

Error 

ErrorHandler(2) 

ErrorMsg 

ErrorMsgHandler(2) 

GetErrorDatabase 

GetErrorDatabaseText 

SetErrorHandler 

SetErrorMsgHandler 

SetWamingHandler 

SetWarningMsgHandler 

S  tringConversion  Warning 

Warning 

WarningMsg 

Event  Handling 

AddEventHandler 

AddExposureToRegion 

Addlnput 

AddRawEventHandler 

AddTimeOut 

AddWorkProc 

AppAddlnput 

AppAddTimeOut 

AppAddWorkProc 

AppMainLoop 

AppNextEvent 

AppPeekEvent 

AppPending 

AppProcessEvent 

BuildEventMask 

DispatchEvent 

EventHandler(2) 

InputCallbackProc  (2) 


Execute  the  procedures  in  a  widget's  callback  list. 
Determine  the  status  of  a  widget's  callback  list. 
Delete  all  procedures  from  a  callback  list. 
Delete  a  procedure  from  a  callback  list. 
Delete  a  list  of  procedures  from  a  callback  list. 


Call  the  installed  fatal  error  procedure. 
Call  the  high-level  fatal  error  handler. 
Obtain  the  error  database. 

Obtain  the  error  database  text  for  an  error  or  a  warning. 
Register  a  procedure  to  be  called  on  fatal  error  conditions. 
Register  a  procedure  to  be  called  on  fatal  error  conditions. 
Register  a  procedure  to  be  called  on  nonfatal  error  conditions. 
Register  a  procedure  to  be  called  on  nonfatal  error  conditions. 
Call  the  installed  nonfatal  error  procedure. 
Call  the  installed  high-level  warning  handler. 
Call  the  low-level  fatal  error  handler. 
Prototype  for  low-level  error  and  warning  handlers. 
Call  the  high-level  fatal  error  handler. 
Prototype  for  high-level  error  and  warning  handlers. 
Obtain  the  error  database. 

Obtain  the  error  database  text  for  an  error  or  a  warning. 
Register  a  procedure  to  be  called  on  fatal  error  conditions. 
Register  a  procedure  to  be  called  on  nonfatal  error  conditions. 
Register  a  procedure  to  be  called  on  nonfatal  error  conditions. 
Register  a  high-level  procedure  to  be  called  on  nonfatal  error  condi 
tions. 

Emit  boilerplate  string  conversion  error  message. 
Call  the  installed  low-level  warning  handler. 
Call  the  installed  high-level  warning  handler. 


Register  a  procedure  to  handle  events. 

Merge  Expose  and  GraphicsExpose  events  into  a  region. 

Register  a  new  file  as  an  input  source  for  an  application. 

Register  an  event  handler  without  selecting  for  the  event. 

Create  a  timeout  value. 

Register  a  work  procedure  for  an  application. 

Register  a  new  file  as  an  input  source  for  a  given  application. 

Invoke  a  procedure  after  a  specified  timeout. 

Register  a  work  procedure  for  a  given  application. 

Process  input  from  a  given  application. 

Return  next  event  from  an  application's  X  event  queue. 

Nondestructively  examine  the  head  of  an  application's  input  queue. 

Determine  whether  any  events  are  in  an  application's  input  queue. 

Process  one  input  event. 

Retrieve  a  widget's  event  mask. 

Dispatch  registered  handlers  for  an  event 

Prototype  event  handler  procedure. 

Prototype  procedure  called  to  handle  file,  pipe,  or  socket  input. 
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InsertEventHandler 
InsertRawEventHandler 

LastTimestampProcessed 

MainLoop 

NextEvent 

PeekEvent 

Pending 

ProcessEvent 

RemoveEventHandler 

Removelnput 

RemoveRawEventHandler 

RemoveTimeOut 

RemoveWorkProc 

TimeiCallbackProc  (2) 

WorkProc(2) 

File  Searching 

FilePredicate(2) 

FindFile 

ResolvePathname 

Geometry  Management 

Configure  Widget 

MakeGeometryRequest 

MakeResizeRequest 

MoveWidget 

OrderProc(2) 

QueryGeometry 

ResizeWidget 

UnmanageChild 

UnmanageChildren 

Graphics  Context 

GetGC 

Initialization 

AppCreateShell 
Applnirialize 

CloseDisplay 
CreateApplicationShell 
DisplayToApplicationContext 
Initialize 


Register  an  event  handler  procedure  that  receives  events  before  or 

after  all  previously  registered  event  handlers. 

Register  an  event  handler  procedure  that  receives  events  before  or 

after  all  previously  registered  event  handlers,  without  selecting  for 

the  events. 

Retrieve  the  timestamp  from  the  most  recent  event  handled  by  Xt- 

DispatchEvent  that  contains  a  timestamp. 

Continuously  process  events. 

Return  next  event  from  input  queue. 

Nondestructively  examine  the  head  of  an  application's  input  queue. 

Determine  if  there  are  any  events  in  an  application's  input  queue. 

Process  one  input  event. 

Remove  a  previously  registered  event  handler. 

Unregister  a  file  procedure,  a  pipe  procedure,  or  a  socket  procedure. 

Remove  a  raw  event  handler. 

Unregister  a  timeout  procedure. 

Unregister  a  work  procedure. 

Prototype  callback  procedure  invoked  when  timeouts  expire. 

Prototype  procedure  for  performing  background  processing. 


Prototype  procedure  used  in  filename  evaluation. 

Search  for  a  file  using  substitutions  in  a  path. 

Search  for  a  file  using  standard  substitutions  in  a  path  list. 


Move  and/or  resize  widget 

Request  parent  to  change  child's  geometry. 

Request  parent  to  change  child's  size. 

Move  a  widget  on  the  display. 

Composite  function  to  determine  position  for  new  child. 

Query  a  child  widget's  preferred  geometry. 

Resize  a  child  or  sibling  widget. 

Remove  a  widget  from  its  parent's  managed  list. 

Remove  a  list  of  children  from  a  parent  widget's  managed  list. 


Obtain  a  read-only,  shareable  GC. 


Create  additional  top-level  widget. 

Initialize  the  X  Toolkit  internals,  create  an  application  context,  open 

a  display,  and  create  the  initial  application  shell  instance. 

Close  a  display  and  remove  it  from  an  application  context. 

Create  an  additional  top-level  widget. 

Retrieve  the  application  context  associated  with  a  Display. 

Initialize  toolkit  and  display. 
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Initialize  WidgetClass 
VaAppCreateShell 

VaAppInitialize 

Keyboard  Handling 

CallAcceptFocus 
CaseProc(2) 
ConvertCase 
GetKeysymTable 

GrabKey 
GrabKeyboard 
KeyProc(2) 
KeysymToKeycodeList 

Regis  terCaseConverter 

S  e  tKeybo  ardFocus 

SetKeyTranslator 

TranslateKey 

TranslateKeycode 

UngrabKey 

UngrabKeyboard 

Memory  Allocation 

Calloc 

DestroyGC 

Free 

Malloc 

MergeArgLists 

New 

NewString 

Realloc 

ReleaseGC 

VaCreateArgsList 

Object  Information 

CheckSubclass 
Class 
Display 
DisplayOfObject 

IsApplicationShell 

IsComposite 

IsConstraint 

IsManaged 

IsObject 

IsOverrideShell 


Initialize  a  widget  class  without  creating  any  widgets. 

Create  a  top-level  widget  that  is  the  root  of  a  widget  tree,  using 

varargs  argument  style. 

Initialize  the  X  Toolkit  internals,  using  varargs  argument  style. 


Call  a  widget's  accept_focus  procedure. 
Prototype  procedure  called  to  convert  the  case  of  keysyms. 
Determine  upper-case  and  lower-case  versions  of  a  keysym. 
Return  a  pointer  to  the  key sym-to -key code  mapping  table  for  a  par 
ticular  display. 

Passively  grab  a  single  key  of  the  keyboard. 
Actively  grab  the  keyboard. 
Prototype  procedure  to  translate  a  key. 

Return  the  list  of  keycodes  that  map  to  a  particular  keysym  in  the 
keyboard  mapping  table  maintained  by  the  Intrinsics. 
Register  a  case  converter. 

Redirect  keyboard  input  to  a  normal  descendant  of  a  child  widget. 
Register  a  key  translator. 
The  default  key  code-to -keysym  translator. 
Invoke  the  currently  registered  keycode-to-keysym  translator. 
Cancel  a  passive  key  grab. 
Cancel  an  active  keyboard  grab. 


Allocate  an  array  and  initialize  elements  to  zero. 

Release  2  compatible  function  to  free  read-only  GCs. 

Free  an  allocated  block  of  storage. 

Allocate  storage. 

Merge  two  ArgList  structures. 

Allocate  storage  for  one  instance  of  a  data  type.  , 

Copy  an  instance  of  a  string. 

Change  the  size  of  an  allocated  block  of  storage. 

Deallocate  a  shared  GC  when  it  is  no  longer  needed. 

Dynamically  allocate  a  varargs  list  for  use  with  the  XtVaNestedList 

symbol  in  multiple  varargs  calls. 


In  DEBUG  mode,  verify  an  object's  class. 

Obtain  a  widget's  class. 

Return  the  display  pointer  for  the  specified  widget 

Return  the  display  pointer  for  the  nearest  ancestor  of  object  that  is  of 

class  Core. 

Test  whether  a  widget  is  a  subclass  of  the  ApplicationShell  widget 

class. 

Test  whether  a  widget  is  a  subclass  of  the  Composite  widget  class. 

Test  whether  a  widget  is  a  subclass  of  the  Constraint  widget  class. 

Determine  whether  a  widget  is  managed  by  its  parent 

Test  whether  a  widget  is  a  subclass  of  the  Object  widget  class. 

Test  whether  a  widget  is  a  subclass  of  the  OverrideShell  widget 

class. 
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IsRealized 

IsRectObj 

Is  Sensitive 

IsShell 

IsSubclass 

IsTopLevelShell 

IsTransientShell 

IsVendorShell 

IsWidget 

IsWMSheU 

Name 

NameToWidget 

Parent 

Screen 

ScreenOfDbject 

Superclass 

Window 

WindowOfObject 

WindowTo  Widget 

Pointer 

GetMultiClickTime 

GrabButton 

GrabPointer 

SetMultiClickTime 

UngrabButton 

UngrabPointer 

Pop  Ups 

AddGrab 

CallbackExclusive 

CallbackNone 

CallbackNonexclusive 

CallbackPopdown 

CreatePopupShell 

MenuPopdown 

MenuPopup 

Popdown 

Popup 

PopupSpringLo  aded 

RemoveGrab 

VaCreatePopupShell 

Properties 

S  etWMCo  lormap  Windows 


Determine  whether  a  widget  has  been  realized. 

Test  whether  a  widget  is  a  subclass  of  the  RectObj  widget  class. 

Check  the  current  sensitivity  state  of  a  widget. 

Test  whether  a  widget  is  a  subclass  of  the  Shell  widget  class. 

Determine  whether  a  widget  is  a  subclass  of  a  class. 

Test  whether  a  widget  is  a  subclass  of  the  TopLevelShell  widget 

class. 

Test  whether  a  widget  is  a  subclass  of  the  TransientShell  widget 

class. 

Test  whether  a  widget  is  a  subclass  of  the  VendorShell  widget  class. 

Test  whether  a  widget  is  a  subclass  of  the  Core  widget  class. 

Test  whether  a  widget  is  a  subclass  of  the  WMShell  widget  class. 

Return  a  pointer  to  the  instance  name  of  the  specified  object. 

Translate  a  widget  name  to  a  widget  instance. 

Return  the  parent  widget  for  the  specified  widget. 

Return  the  screen  pointer  for  the  specified  widget. 

Return  the  screen  pointer  for  the  nearest  ancestor  of  object  that  is  of 

class  Core. 

Obtain  a  widget's  superclass. 

Return  the  window  of  the  specified  widget. 

Return  the  window  for  the  nearest  ancestor  of  object  that  is  of  class 

Core. 

Translate  a  window  and  display  pointer  into  a  widget  ID. 


Read  the  multi-click  time. 

Passively  grab  a  single  pointer  button. 

Actively  grab  the  pointer. 

Set  the  multi-click  time  dynamically. 

Cancel  a  passive  button  grab. 

Cancel  an  active  pointer  grab. 


Redirect  user  input  to  a  modal  widget. 

Callback  function  to  pop  up  a  widget. 

Callback  function  to  pop  up  a  widget. 

Callback  function  to  pop  up  a  widget. 

Pop  down  a  widget  from  a  callback  routine. 

Create  a  pop-up  shell. 

Built-in  action  for  popping  down  a  widget. 

Built-in  action  for  popping  up  a  widget. 

Unmap  a  pop-up  shell. 

Map  a  pop-up  shell. 

Map  a  spring-loaded  pop-up  from  within  an  application. 

Redirect  user  input  from  modal  widget  back  to  normal  destination. 

Create  a  pop-up  shell,  using  varargs  argument  style. 


Set  WM_COLORMAP_WINDOWS  property  to  inform  window  man 
ager  of  custom  colormaps. 
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Resource  Management 

AddConverter 

AppAddConverter 

AppReleaseCacheRefs 

AppSetFallbackResources 

AppSetTypeConverter 

CallbackReleaseCacheRef 

CallbackReleaseCacheRefList 

CallConverter 

Convert 

ConvertAndStore 

ConvertArgProc  (2) 

Converter  (2) 

Database 

Destructor  (2) 

DirectConvert 

DisplayStringConversionWaming 

GetApplicationResources 

GetCons  train  tResourceList 

GetResourceList 

GetSubresources 

GetSubvalues 

GetValues 

Offset 

OffsetOf 

ResourceDefaultProc  (2) 

S  etMappedWhenM  anaged 

SetSensitive 

SetSubvalues 

SetTypeConverter 

SetValues 

TypeConverter(2) 

VaGetApplicationResources 

VaGetSubresources 
VaGetSubvalues 

VaGetValues 

VaSetSubvalues 

VaSetValues 


Selections 

AppGetS  electionTimeout 
AppSetSelectionTimeout 
CancelConvertSelectionProc  (2) 


Register  a  new  resource  converter. 
Register  a  new  resource  converter  for  an  application. 
Explicitly  decrement  the  reference  counts  for  cached  resources 
obtained  from  XtCallConverter. 
Specify  a  default  set  of  resource  values. 
Register  a  type  converter  in  a  single  application  context. 
Callback  function  to  release  a  cached  resource  value. 
Callback  function  to  release  a  list  of  cached  values. 
Explicitly  invoke  resource  conversions. 
Convert  resource  type. 

Look  up  and  call  a  resource  converter,  copying  the  resulting  value. 
Prototype  procedure  for  argument  conversion. 
Prototype  procedure  for  an  old-style  resource 
Obtain  the  resource  database  for  a  particular  display. 
Prototype  procedure  to  destroy  cached  resource  data. 
Perform  resource  conversion  and  cache  result. 
Issue  a  warning  message  during  conversion  of  string  resource  val 
ues. 

Set  application  variables  from  resource  database. 
Get  the  constraint  resource  list  structure  for  a  particular  widget  class. 
Retrieve  default  values  for  a  resource  list. 

Update  subpart  resource  list. 

Copy  from  subpart  data  structure  to  the  argument  list. 

Copy  resources  from  a  widget  to  the  argument  list. 

Determine  the  byte  offset  of  a  field  within  a  structure  pointer  type. 

Determine  the  byte  offset  of  a  field  within  a  structure  type. 

Prototype  procedure  passed  as  a  resource  converter  when  XtRCall- 

Proc  is  specified  in  a  resource  list  entry. 

Change  the  value  of  a  widget's  map_when_managed  field. 

Set  the  sensitivity  state  of  a  widget.  , 

Copy  resource  settings  from  an  ArgList  to  a  subpart  resource  list. 

Register  a  type  converter  for  all  application  contexts  in  a  process. 

Copy  resources  from  an  ArgList  to  a  widget. 

Prototype  procedure  for  a  new-style  resource  converter. 

Retrieve  resources  for  the  overall  application  using  varargs  argu 
ment  style. 

Fetch  resources  for  widget  subparts,  using  varargs  argument  style. 

Retrieve  the  current  values  of  nonwidget  resources  associated  with  a 

widget  instance,  using  varargs  argument  style. 

Retrieve  the  current  values  of  resources  associated  with  a  widget 

instance,  using  varargs  argument  style. 

Set  the  current  values  of  nonwidget  resources  associated  with  a 

widget  instance,  using  varargs  argument  style. 

Modify  the  current  resource  values  associated  with  a  widget 

instance,  using  varargs  argument  style. 


Get  the  current  selection  timeout  value. 

Set  the  Intrinsics  selection  timeout. 

Prototype  procedure  to  cancel  incremental  selection  transfer. 
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ConvertSelectionlncrProc  (2) 
ConvertSelectionProc  (2) 
Disc  wnS  election 
GetSelectionRequest 

GetSelectionTimeout 

GetS  election  Value 

GetS  election  Valuelncremental 

GetSelection  Values 

GetSelectionValuesIncremental 

LoseSelectionlncrProc  (2) 

LoseSelectionProc  (2) 

OwnSelection 
OwnSelectionlncremental 
SelectionCallbackProc  (2) 
SelectionDonelncrProc  (2) 
SelectionDoneProc  (2) 
SetSelectionTimeout 

Translations  and  Actions 

ActionHookProc  (2) 

ActionProc(2) 

AddActions 

AppAddActionHook 

AppAddActions 

AugmentTranslations 

CallActionProc 
GetActionKeysym 

InstallAccelerators 
InstallAllAccelerators 

OverrideTranslations 
ParseAcceleratorTable 
ParseTranslationTable 
Regis  terGrabAction 

RemoveActionHook 
UninstallTranslations 

Widget  LIfecycle 

CreateManagedWidget 

CreateWidget 

DestroyWidget 

ManageChild 

ManageChildren 

MapWidget 

RealizeWidget 

UnmapWidget 


Prototype  procedure  to  convert  incremental  selection  data. 

Prototype  procedure  to  convert  selection  data. 

Indicate  that  selection  data  is  no  longer  available. 

Retrieve  the  SelectionRequest  event  that  triggered  the  XtConvert- 

SelectionProc. 

Get  the  current  selection  timeout  value. 

Obtain  the  complete  selection  data. 

Obtain  the  selection  value  using  incremental  transfers. 

Obtain  selection  data  in  multiple  formats. 

Obtain  multiple  selection  values  using  incremental  transfers. 

Prototype  procedure  to  release  incremental  selection  ownership. 

Prototype  procedure  called  by  Xt  when  another  client  claims  the 

selection. 

Indicate  that  selection  data  is  available. 

Set  the  selection  owner  when  using  incremental  transfers. 

Prototype  procedure  called  when  requested  selection  data  arrives. 

Prototype  procedure  to  indicate  completion  of  incremental  transfer. 

Prototype  procedure  called  after  a  data  transfer  completes. 

Set  value  of  selection  timeout. 


Prototype  action  hook  procedure. 
Prototype  action  procedure. 

Register  an  action  table  with  the  Translation  Manager. 
Add  an  action  hook. 

Declare  an  action  table  and  register  it  with  the  Resource  Manager. 
Nondestructively  merge  new  translations  with  widget's  existing 
ones. 

Invoke  an  action  procedure  without  generating  events. 
Retrieve  the  keysym  and  modifiers  that  matched  the  final  event 
specification  in  the  translation  table  entry. 
Install  a  widget's  accelerators  on  another  widget 
Install  all  accelerators  from  a  widget  and  its  descendants  onto  a  des 
tination  widget. 

Merge  new  translations,  overwriting  widget's  existing  ones. 
Compile  an  accelerator  table  into  its  internal  representation. 
Compile  a  translation  table  into  its  internal  representation. 
Register  button  and  key  grabs  for  a  widget's  window  according  to 
the  event  bindings  in  the  widget's  translation  table. 
Unregister  an  action  hook  procedure. 
Remove  existing  translations. 


Create  and  manage  a  child  widget. 

Create  an  instance  of  a  widget. 

Destroy  a  widget  instance. 

Add  a  widget  to  its  parent's  list  of  managed  children. 

Add  widgets  to  their  parent's  list  of  managed  children. 

Map  a  widget  to  its  display. 

Realize  a  widget  instance. 

Unmap  a  widget  explicitly. 
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UnrealizeWidget 
VaCreateManagedWidget 

VaCreateWidget 

Window  Manipulation 

CreateWindow 
ResizeWindow 
TranslateCoords 


Destroy  the  windows  associated  with  a  widget  and  its  descendants. 
Create  and  manage  a  child  widget  in  a  single  procedure,  using 
varargs  argument  style. 
Create  an  instance  of  a  widget  using  varargs  argument  style. 


Create  widget's  working  window. 

Resize  a  widget  according  to  its  core  dimensions. 

Translate  an  x-y  coordinate  pair  from  widget  coordinates  to  root 

coordinates. 


Alphabetical  Listing 


ActionHookProc 

ActionProc 

AddActions 

AddCallback 

AddCallbacks 

AddConverter 

AddEventHandler 

AddExposureToRegion 

AddGrab 

Addlnput 

AddRawEventHandler 

AddTimeOut 

AddWorkProc 

AppAddActionHook 

AppAddActions 

AppAddConverter 

AppAddlnput 

AppAddTimeOut 

AppAddWorkProc 

AppCreateShell 

AppError 

AppErrorMsg 

AppGetErrorDatabase 

AppGetErrorDatabaseText 

AppGetS  electionTimeout 

Applnitialize 

AppMainLoop 

AppNextEvent 

AppPeekEvent 

AppPending 

AppProcessEvent 


Prototype  action  hook  procedure. 

Prototype  action  procedure. 

Register  an  action  table  with  the  Translation  Manager. 

Add  a  callback  procedure  to  a  widget's  callback  resource. 

Add  a  list  of  callback  procedures  to  a  given  widget's  callback  list. 

Register  a  new  resource  converter. 

Register  a  procedure  to  handle  events. 

Merge  Expose  and  GraphicsExpose  events  into  a  region. 

Redirect  user  input  to  a  modal  widget. 

Register  a  new  file  as  an  input  source  for  an  application. 

Register  an  event  handler  without  selecting  for  the  event. 

Create  a  timeout  value. 

Register  a  work  procedure  for  an  application. 

Add  an  action  hook. 

Declare  an  action  table  and  register  it  with  the  Resource  Manager. 

Register  a  new  resource  converter  for  an  application. 

Register  a  new  file  as  an  input  source  for  a  given  application. 

Invoke  a  procedure  after  a  specified  timeout. 

Register  a  work  procedure  for  a  given  application. 

Create  additional  top-level  widget. 

Call  the  installed  fatal  error  procedure. 

Call  the  high-level  fatal  error  handler. 

Obtain  the  error  database. 

Obtain  the  error  database  text  for  an  error  or  a  warning. 

Get  the  current  selection  timeout  value. 

Initialize  the  X  Toolkit  internals,  create  an  application  context,  open  a 

display,  and  create  the  initial  application  shell  instance. 

Process  input  from  a  given  application. 

Return  next  event  from  an  application's  X  event  queue. 

Nondestructively  examine  the  head  of  an  application's  input  queue. 

Determine  whether  any  events  are  in  an  application's  input  queue. 

Process  one  input  event. 
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AppReleaseCacheRefs 

AppSetErrorHandler 

AppSetErrorMsgHandler 

AppSetFallbackResources 

AppSetSelectionTimeout 

AppSetTypeConverter 

AppSetWarningHandler 

AppSetWarningMsgHandler 

AppWarning 

AppWamingMsg 

AugmentTranslations 

BuildEventMask 

CallAcceptFocus 

CallActionProc 

CallbackExclusive 

CallbackNone 

CallbackNonexclusive 

CallbackPopdown 

CaUbackProc 

CaUbackReleaseCacheRef 

CallbackReleaseCacheRefList 

CallCallbackList 

CallCallbacks 

CallConverter 

Calloc 

CancelConvertSelectionProc 

CaseProc 

CheckSubclass 

Class 

CloseDisplay 

Configure  Widget 

Convert 

ConvertAndS  tore 

ConvertArgProc 

ConvertC  ase 

Converter 

ConvertSelectionlncrProc 

ConvertSelectionProc 

CreateApplicationContext 

CreateApplicationShell 

CreateManagedWidget 

CreatePopupShell 

CreateWidget 

CreateWindow 

Database 


Explicitly  decrement  the  reference  counts  for  cached  resources 

obtained  from  XtCallConverter. 

Register  a  procedure  to  be  called  on  fatal  error  conditions. 

Register  a  procedure  to  be  called  on  fatal  error  conditions. 

Specify  a  default  set  of  resource  values. 

Set  the  Litrinsics  selection  timeout. 

Register  a  type  converter  in  a  single  application  context. 

Register  a  procedure  to  be  called  on  nonfatal  error  conditions. 

Register  a  procedure  to  be  called  on  nonfatal  error  conditions. 

Call  the  installed  nonfatal  error  procedure. 

Call  the  installed  high-level  warning  handler. 

Nondestructively  merge  new  translations  with  widget's  existing  ones. 

Retrieve  a  widget's  event  mask. 

Call  a  widget's  accept_focus  procedure. 

Invoke  an  action  procedure  without  generating  events. 

Callback  function  to  pop  up  a  widget. 

Callback  function  to  pop  up  a  widget. 

Callback  function  to  pop  up  a  widget. 

Pop  down  a  widget  from  a  callback  routine. 

Prototype  callback  procedure. 

Callback  function  to  release  a  cached  resource  value. 

Callback  function  to  release  a  list  of  cached  values. 

Execute  the  procedures  in  a  callback  list,  specifying  the  callback  list 

by  address. 

Execute  the  procedures  in  a  widget's  callback  list. 

Explicitly  invoke  resource  conversions. 

Allocate  an  array  and  initialize  elements  to  zero. 

Prototype  procedure  to  cancel  incremental  selection  transfer. 

Prototype  procedure  called  to  convert  the  case  of  keysyms. 

In  DEBUG  mode,  verify  an  object's  class. 

Obtain  a  widget's  class. 

Close  a  display  and  remove  it  from  an  application  context. 

Move  and/or  resize  widget 

Convert  resource  type. 

Look  up  and  call  a  resource  converter,  copying  the  resulting  value. 

Prototype  procedure  for  argument  conversion. 

Determine  upper-case  and  lower-case  versions  of  a  keysym. 

Prototype  procedure  for  an  old-style  resource 

Prototype  procedure  to  convert  incremental  selection  data. 

Prototype  procedure  to  convert  selection  data. 

Create  an  application  context. 

Create  an  additional  top-level  widget. 

Create  and  manage  a  child  widget 

Create  a  pop-up  shell. 

Create  an  instance  of  a  widget 

Create  widget's  working  window. 

Obtain  the  resource  database  for  a  particular  display. 
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Destroy  an  application  context  and  close  its  displays. 

Release  2  compatible  function  to  free  read-only  GCs. 

Destroy  a  widget  instance. 

Prototype  procedure  to  destroy  cached  resource  data. 

Perform  resource  conversion  and  cache  result. 

Indicate  that  selection  data  is  no  longer  available. 

Dispatch  registered  handlers  for  an  event. 

Return  the  display  pointer  for  the  specified  widget 

Initialize  a  display  and  add  it  to  an  application  context. 

Return  the  display  pointer  for  the  nearest  ancestor  of  object  that  is  of 

class  Core. 

Display  S  tringConversionWarning 

Issue  a  warning  message  during  conversion  of  string  resource  values. 

Retrieve  the  application  context  associated  with  a  Display. 

Call  the  low-level  fatal  error  handler. 

Prototype  for  low-level  error  and  warning  handlers. 

Call  the  high-level  fatal  error  handler. 

Prototype  for  high-level  error  and  warning  handlers. 

Prototype  event  handler  procedure. 

Prototype  procedure  used  in  filename  evaluation. 

Search  for  a  file  using  substitutions  in  a  path. 

Free  an  allocated  block  of  storage. 

Retrieve  the  keysym  and  modifiers  that  matched  the  final  event  speci 
fication  in  the  translation  table  entry. 
GetApplicationNameAndClass     Return  the  application  name  and  class  as  passed  to  XtDisplaylnitialize 

for  a  particular  Display. 

Set  application  variables  from  resource  database. 

Get  the  constraint  resource  list  structure  for  a  particular  widget  class. 

Obtain  the  error  database. 

Obtain  the  error  database  text  for  an  error  or  a  warning.    • 

Obtain  a  read-only,  shareable  GC. 

Return  a  pointer  to  the  keysym-to-keycode  mapping  table  for  a  partic 
ular  display. 

Read  the  multi-click  time. 

Retrieve  default  values  for  a  resource  list 

Retrieve  the  SelectionRequest  event  that  triggered  the  XtConvert- 

SelectionProc. 

Get  the  current  selection  timeout  value. 

Obtain  the  complete  selection  data. 

Obtain  the  selection  value  using  incremental  transfers. 

Obtain  selection  data  in  multiple  formats. 
GetSelectionValuesIncremental    Obtain  multiple  selection  values  using  incremental  transfers. 
GetSubresources  Update  subpart  resource  list 

GetSubvalues  Copy  from  subpart  data  structure  to  the  argument  list. 

GetValues  Copy  resources  from  a  widget  to  the  argument  list. 

GrabButton  Passively  grab  a  single  pointer  button. 

GrabKey  Passively  grab  a  single  key  of  the  keyboard. 


Destroy  ApplicationContext 

DestroyGC 

DestroyWidget 

Destructor 

DirectConvert 

DisownSelection 

DispatchEvent 

Display 

Displaylnitialize 

DisplayOfObject 


DisplayToApplicationContext 

Error 

ErrorHandler 

ErrorMsg 

ErrorMsgHandler 

EventHandler 

FilePredicate 

FindFile 

Free 

GetActionKeysym 


GetApplicationResources 

GetConstraintResourceList 

GetErrorDatabase 

GetErrorDatabaseText 

GetGC 

GetKeysymTable 

GetMultiClickTime 

GetResourceList 

GetSelectionRequest 

GetSelectionTimeout 
GetSelection  Value 
GetSelectionValuelncremental 
GetS  election  Values 
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GrabKeyboard 

GrabPointer 

HasCallbacks 

Initialize 

Initialize  WidgetClass 

InputCallbackProc 

InsertEventHandler 

InsertRawEventHandler 


InstallAccelerators 
InstallAllAccelerators 

IsApplicationShell 

IsComposite 

IsConstraint 

IsManaged 

IsObject 

IsOverrideShell 

IsRealized 

IsRectObj 

IsSensitive 

IsShell 

IsSubclass 

IsTopLevelShell 

IsTransientShell 

IsVendorShell 

IsWidget 

IsWMShell 

KeyProc 

KeysymToKeycodeList 

LastTimestampProcessed 

LoseSelectionlncrProc 
LoseSelectionProc 

MainLoop 

MakeGeometry  Reques  t 

MakeResizeRequest 

Malloc 

ManageChild 

ManageChildren 

Map  Widget 

MenuPopdown 

MenuPopup 


Actively  grab  the  keyboard. 
Actively  grab  the  pointer. 
Determine  the  status  of  a  widget's  callback  list. 
Initialize  toolkit  and  display. 

Initialize  a  widget  class  without  creating  any  widgets. 
Prototype  procedure  called  to  handle  file,  pipe,  or  socket  input. 
Register  an  event  handler  procedure  that  receives  events  before  or 
after  all  previously  registered  event  handlers. 
Register  an  event  handler  procedure  that  receives  events  before  or 
after  all  previously  registered  event  handlers,  without  selecting  for  the 
events. 

Install  a  widget's  accelerators  on  another  widget 
Install  all  accelerators  from  a  widget  and  its  descendants  onto  a  desti 
nation  widget. 

Test  whether  a  widget  is  a  subclass  of  the  ApplicationShell  widget 
class. 

Test  whether  a  widget  is  a  subclass  of  the  Composite  widget  class. 
Test  whether  a  widget  is  a  subclass  of  the  Constraint  widget  class. 
Determine  whether  a  widget  is  managed  by  its  parent. 
Test  whether  a  widget  is  a  subclass  of  the  Object  widget  class. 
Test  whether  a  widget  is  a  subclass  of  the  OverrideShell  widget  class. 

Determine  whether  a  widget  has  been  realized. 

Test  whether  a  widget  is  a  subclass  of  the  RectObj  widget  class. 

Check  the  current  sensitivity  state  of  a  widget. 

Test  whether  a  widget  is  a  subclass  of  the  Shell  widget  class. 

Determine  whether  a  widget  is  a  subclass  of  a  class. 

Test  whether  a  widget  is  a  subclass  of  the  TopLevelShell  widget  class. 

Test  whether  a  widget  is  a  subclass  of  the  TransientShell  widget  class. 

Test  whether  a  widget  is  a  subclass  of  the  VendorShell  widget  class. 

Test  whether  a  widget  is  a  subclass  of  the  Core  widget  class. 

Test  whether  a  widget  is  a  subclass  of  the  WMShell  widget  class. 

Prototype  procedure  to  translate  a  key. 

Return  the  list  of  keycodes  that  map  to  a  particular  keysym  in  the  key 
board  mapping  table  maintained  by  the  Intrinsics. 

Retrieve  the  timestamp  from  the  most  recent  event  handled  by  Xt- 

DispatchEvent  that  contains  a  timestamp. 

Prototype  procedure  to  release  incremental  selection  ownership. 

Prototype  procedure  called  by  Xt  when  another  client  claims  the  selec 
tion. 

Continuously  process  events. 

Request  parent  to  change  child's  geometry. 

Request  parent  to  change  child's  size. 

Allocate  storage. 

Add  a  widget  to  its  parent's  list  of  managed  children. 

Add  widgets  to  their  parent's  list  of  managed  children. 

Map  a  widget  to  its  display. 

Built-in  action  for  popping  down  a  widget. 

Built-in  action  for  popping  up  a  widget. 
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MergeArgLists 

MoveWidget 

Name 

NameToWidget 

New 

NewString 

NextEvent 

Number 

Offset 

OffsetOf 

OpenDisplay 

OrderProc 

OverrideTranslations 

OwnSelection 

O  wnS  electionlncremental 

Parent 

ParseAcceleratorTable 

ParseTranslationTable 

PeekEvent 

Pending 

Popdown 

Popup 

PopupSpringLoaded 

ProcessEvent 

QueryGeometry 

RealizeWidget 

Realloc 

Regis  terCaseConverter 

Regis  terGrabAction 

ReleaseGC 

RemoveActionHook 

RemoveAllCallbacks 

RemoveCallback 

RemoveCallbacks 

RemoveEventHandler 

RemoveGrab 

Removelnput 

RemoveRawEventHandler 

RemoveTimeOut 

RemoveWorkProc 

ResizeWidget 

ResizeWindow 

ResolvePathname 

ResourceDefaultProc 

Screen 


Merge  two  ArgList  structures. 

Move  a  widget  on  the  display. 

Return  a  pointer  to  the  instance  name  of  the  specified  object. 

Translate  a  widget  name  to  a  widget  instance. 

Allocate  storage  for  one  instance  of  a  data  type. 

Copy  an  instance  of  a  string. 

Return  next  event  from  input  queue. 

Determine  the  number  of  elements  in  a  fixed-size  array. 

Determine  the  byte  offset  of  a  field  within  a  structure  pointer  type. 

Determine  the  byte  offset  of  a  field  within  a  structure  type. 

Open,  initialize,  and  add  a  display  to  an  application  context. 

Composite  function  to  determine  position  for  new  child. 

Merge  new  translations,  overwriting  widget's  existing  ones. 

Indicate  that  selection  data  is  available. 

Set  the  selection  owner  when  using  incremental  transfers. 

Return  the  parent  widget  for  the  specified  widget. 

Compile  an  accelerator  table  into  its  internal  representation. 

Compile  a  translation  table  into  its  internal  representation. 

Nondestructively  examine  the  head  of  an  application's  input  queue. 

Determine  if  there  are  any  events  in  an  application's  input  queue. 

Unmap  a  pop-up  shell. 

Map  a  pop-up  shell. 

Map  a  spring-loaded  pop-up  from  within  an  application. 

Process  one  input  event. 

Query  a  child  widget's  preferred  geometry. 

Realize  a  widget  instance. 

Change  the  size  of  an  allocated  block  of  storage. 

Register  a  case  converter. 

Register  button  and  key  grabs  for  a  widget's  window  according  to  the 

event  bindings  in  the  widget's  translation  table. 

Deallocate  a  shared  GC  when  it  is  no  longer  needed. 

Unregister  an  action  hook  procedure. 

Delete  all  procedures  from  a  callback  list. 

Delete  a  procedure  from  a  callback  list. 

Delete  a  list  of  procedures  from  a  callback  list. 

Remove  a  previously  registered  event  handler. 

Redirect  user  input  from  modal  widget  back  to  normal  destination. 

Unregister  a  file  procedure,  a  pipe  procedure,  or  a  socket  procedure. 

Remove  a  raw  event  handler. 

Unregister  a  timeout  procedure. 

Unregister  a  work  procedure. 

Resize  a  child  or  sibling  widget 

Resize  a  widget  according  to  its  core  dimensions. 

Search  for  a  file  using  standard  substitutions  in  a  path  list. 

Prototype  procedure  passed  as  a  resource  converter  when  XtRCallProc 

is  specified  in  a  resource  list  entry. 

Return  the  screen  pointer  for  the  specified  widget. 
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ScreenOfObject 

SelectionCallbackProc 

S  electionDonelncrProc 

SelectionDoneProc 

SetArg 

SetErrorHandler 

SetErrorMsgHandler 

SetKeyboardFocus 

SetKeyTranslator 

SetMappedWhenManaged 

SetMultiClickTime 

S  etS  electionTimeout 

SetSensitive 

SetSubvalues 

SetTypeConverter 

SetValues 

SetWarningHandler 

SetWamingMsgHandler 

SetWMColormapWindows 

StringConversion  Warning 

Superclass 

TimerCallbackProc 

Toolkitlnitialize 

TranslateCoords 

TranslateKey 

TranslateKeycode 

TypeConverter 

UngrabButton 

UngrabKey 

UngrabKeyboard 

UngrabPointer 

UninstallTranslations 

UnmanageChild 

UnmanageChildren 

UnmapWidget 

UnrealizeWidget 

VaAppCreateShell 

VaAppInitialize 
VaCreateArgsList 

VaCreateManagedWidget 


Return  the  screen  pointer  for  the  nearest  ancestor  of  object  that  is  of 
class  Core. 

Prototype  procedure  called  when  requested  selection  data  arrives. 
Prototype  procedure  to  indicate  completion  of  incremental  transfer. 
Prototype  procedure  called  after  a  data  transfer  completes. 
Modify  an  argument  list  dynamically. 
Register  a  procedure  to  be  called  on  fatal  error  conditions. 
Register  a  procedure  to  be  called  on  nonfatal  error  conditions. 
Redirect  keyboard  input  to  a  normal  descendant  of  a  child  widget. 
Register  a  key  translator. 

Change  the  value  of  a  widget's  map_when_managed  field. 
Set  the  multi-click  time  dynamically. 
Set  value  of  selection  timeout. 
Set  the  sensitivity  state  of  a  widget. 

Copy  resource  settings  from  an  ArgList  to  a  subpart  resource  list. 
Register  a  type  converter  for  all  application  contexts  in  a  process. 
Copy  resources  from  an  ArgList  to  a  widget. 
Register  a  procedure  to  be  called  on  nonfatal  error  conditions. 
Register  a  high-level  procedure  to  be  called  on  nonfatal  error  condi 
tions. 

Set  WM_COLORMAP_WINDOWS  property  to  inform  window  man 
ager  of  custom  colormaps. 
Emit  boilerplate  string  conversion  error  message. 
Obtain  a  widget's  superclass. 

Prototype  callback  procedure  invoked  when  timeouts  expire. 
Initialize  the  X  Toolkit  internals. 

Translate  an  x-y  coordinate  pair  from  widget  coordinates  to  root  coor 
dinates. 

The  default  key  code-to -key  sym  translator. 
Invoke  the  currently  registered  keycode-to-keysym  translator. 
Prototype  procedure  for  a  new-style  resource  converter. 
Cancel  a  passive  button  grab. 
Cancel  a  passive  key  grab. 
Cancel  an  active  keyboard  grab. 
Cancel  an  active  pointer  grab. 
Remove  existing  translations. 
Remove  a  widget  from  its  parent's  managed  list. 
Remove  a  list  of  children  from  a  parent  widget's  managed  list. 
Unmap  a  widget  explicitly. 

Destroy  the  windows  associated  with  a  widget  and  its  descendants. 
Create  a  top-level  widget  that  is  the  root  of  a  widget  tree,  using  varargs 
argument  style. 

Initialize  the  X  Toolkit  internals,  using  varargs  argument  style. 
Dynamically  allocate  a  varargs  list  for  use  with  the  XtVaNestedList 
symbol  in  multiple  varargs  calls. 

Create  and  manage  a  child  widget  in  a  single  procedure,  using  varargs 
argument  style. 
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VaCreatePopupShell 

VaCreateWidget 

VaGetApplicationResources 

VaGetSubresources 
VaGetSubvalues 

VaGetValues 

VaSetSubvalues 

VaSetValues 

Warning 

WarningMsg 

WidgetToApplicationContext 

Window 

WindowOfObject 

WindowToWidget 
WorkProc 


Create  a  pop-up  shell,  using  varargs  argument  style. 

Create  an  instance  of  a  widget  using  varargs  argument  style. 

Retrieve  resources  for  the  overall  application  using  varargs  argument 

style. 

Fetch  resources  for  widget  subparts,  using  varargs  argument  style. 

Retrieve  the  current  values  of  nonwidget  resources  associated  with  a 

widget  instance,  using  varargs  argument  style. 

Retrieve  the  current  values  of  resources  associated  with  a  widget 

instance,  using  varargs  argument  style. 

Set  the  current  values  of  nonwidget  resources  associated  with  a  widget 

instance,  using  varargs  argument  style. 

Modify  the  current  resource  values  associated  with  a  widget  instance, 

using  varargs  argument  style. 

Call  the  installed  low-level  warning  handler. 

Call  the  installed  high-level  warning  handler. 

Get  the  application  context  for  a  given  widget. 

Return  the  window  of  the  specified  widget. 

Return  the  window  for  the  nearest  ancestor  of  object  that  is  of  class 

Core. 

Translate  a  window  and  display  pointer  into  a  widget  ID. 

Prototype  procedure  for  performing  background  processing. 
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B 

X  Toolkit  Data  Types 


This  appendix  summarizes  the  data  types  used  as  arguments  or  return  values  in  Xt  Intrinsics 
functions.  Unless  otherwise  noted,  these  types  are  defined  in  the  header  file  XI 1 1  Intrinsic,  h. 
Data  types  (which  include  simple  typedefs  as  well  as  structures  and  enums)  are  listed  alpha 
betically.  Defined  symbols  (for  example,  constants  used  to  specify  the  value  of  a  mask  or  a 
field  in  a  structure)  or  other  data  types  used  only  to  set  structure  members  are  listed  with  the 
data  type  in  which  they  are  used. 

Arg 

See  ArgList. 

ArgList 

An  ArgList  is  used  for  setting  resources  in  calls  to  create  a  widget  (XtCreate- 
Widget,  XtCreateManagedWidget,  XtCreatePopupShell)  as  well  as  in 
calls  to  set  or  get  resources  (XtSetValues,  xtGetValues,  xtSetSubvalues, 
XtGetSubvalues,  XtSetSubresources,  XtGetSubresources).  It  is 
defined  as  follows  in  <X1  II Intrinsic. h>: 

typedef  struct  { 

String      name; 

XtArgVal    value; 
}  Arg,  *ArgList; 

The  name  field  is  typically  a  defined  constant  of  the  form  xtNresource/ia/ne  from 
either  <XlllStringdefs.h>  or  a  widget  public  header  file.  It  identifies  the  name  of  the 
argument  to  be  set  The  value  field  is  an  XtArgVal,  a  system-dependent  typedef 
chosen  to  be  large  enough  to  hold  a  pointer  to  a  function.  It  is  often  not  large  enough  to 
hold  a  float  or  double. 

Atom 

To  optimize  communication  with  the  server,  a  property  is  referenced  by  string  name  only 
once,  and  subsequently  by  a  unique  integer  ID  called  an  Atom.  Predefined  atoms  are 
defined  in  <Xll/Xatom.h>  using  defined  symbols  beginning  with  XA_;  other  atoms  can 
be  obtained  from  the  server  by  calling  the  Xlib  function  XinternAtom.  The  Xmu 
library  supports  an  atom-caching  mechanism  to  reduce  the  number  of  XinternAtom 
calls  that  may  be  required.  For  more  information,  see  Chapter  10,  Interclient  Commu 
nication,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 


Appendix  B:  X  Toolkit  Data  Types  631 


Boolean 

A  typedef  from  <X1  II  Intrinsic.  h>  used  to  indicate  True  (1)  or  False  (0).  Use  either 
the  symbols  TRUE  or  FALSE,  defined  in  <X  11  /Intrinsic.  h>  or  True  or  False,  defined  in 


Cardinal 

A  typedef  from  <X1  II  Intrinsic.  h>  used  to  specify  any  unsigned  integer  value. 

Cursor 

An  XID  (server  resource  ID)  that  identifies  a  cursor  resource  maintained  by  the  server.  A 
Cursor  can  be  returned  from  any  of  the  Xlib  calls  XCreateFontCursor  (which 
creates  a  cursor  from  the  set  of  standard  cursors  contained  in  the  cursor  font), 
XGreateGlyphCursor  (which  creates  a  cursor  from  any  other  font  glyph),  or 
XCreatePixmapCursor  (which  creates  a  cursor  from  a  bitmap  image.)  In  Xt,  the 
only  occasion  when  you  specify  a  Cursor  is  in  a  call  to  XtGrabButton  or  Xt- 
GrabPointer,  as  the  cursor  to  be  displayed  during  a  grab.  The  cursor  resource  must 
already  be  allocated  by  an  Xlib  call. 

Dimension 

A  typedef  from  <X1  II  Intrinsic.  h>  used  to  specify  window  sizes.  The  Dimension  data 
type  was  introduced  in  R3  to  increase  portability.  R2  applications  that  specified  dimen 
sions  as  int  should  use  Dimension  instead. 

Display 

A  structure  defined  in  <Xll/Xlib.h>  that  contains  information  about  the  display  the  pro 
gram  is  running  on.  Display  structure  fields  should  not  be  accessed  directly;  Xlib  pro 
vides  a  number  of  macros  to  return  essential  values.  In  Xt,  a  pointer  to  the  current 
Display  is  returned  by  a  call  to  XtDisplay.  XtOpenDisplay  can  be  used  to 
explicitly  open  more  than  one  Display. 

EventMask 

A  typedef  from  <X1  II  Intrinsic.  h>  used  to  specify  which  events  are  selected'  by  an  event 
handler.  Specify  the  value  as  the  bitwise  OR  of  any  of  the  following  symbols  defined  in 


Circumstances 


Event  Mask  Symbol 


NoEventMask 

KeyPressMask 

KeyReleaseMask 

Button? re ssMask 

ButtonReleaseMask 

EnterWindowMask 

LeaveWindowMask 

Point erMotionMask 

PointerMotionHintMask 

ButtonlMotionMask 

Button2MotionMask 

Button3MotionMask 

Button4MotionMask 

ButtonSMotionMask 


No  events 

Keyboard  down  events 
Keyboard  up  events 
Pointer  button  down  events 
Pointer  button  up  events 
Pointer  window  entry  events 
Pointer  window  leave  events 
All  pointer  motion  events 
Fewer  pointer  motion  events 
Pointer  motion  while  button  1  down 
Pointer  motion  while  button  2  down 
Pointer  motion  while  button  3  down 
Pointer  motion  while  button  4  down 
Pointer  motion  while  button  5  down 


632 


X  Toolkit  Intrinsics  Reference  Manual 


Event  Mask  Symbol 


ButtonMotionMask 
KeymapStateMask 

ExposureMask 

VisibilityChangeMask 

StructureNotifyMask 

ResizeRedirectMask 

SubstructureNotifyMask 

SubstructureRedirectMask 

FocusChangeMask 

PropertyChangeMask 

ColormapChangeMask 

Owner GrabButtonMask 


Circumstances 


Pointer  motion  while  any  button  down 

Any  keyboard  state  change  on  EnterNotif  y, 

LeaveNotif  y,  Focusln,  or  FocusOut 

Any  exposure  (except  GraphicsExpose  and 

NoExpose) 

Any  change  in  visibility 

Any  change  in  window  configuration 

Redirect  resize  of  this  window 

Notify  about  reconfiguration  of  children 

Redirect  reconfiguration  of  children 

Any  change  in  keyboard  focus 

Any  change  in  property 

Any  change  in  colormap 

Modifies  handling  of  pointer  events 


GC 


plus  the  following  symbol  defined  in  <X1  II Intrinsic. h>: 
xtAllEvents       All  of  the  above  masks:      (  (EventMask)    -1L) 

See  Appendix  C,  Event  Reference,  for  more  information  on  each  of  the  events  selected  by 
these  mask  values.  The  xtBuildEventMask  function  returns  the  event  mask  repre 
senting  the  logical  OR  of  all  event  masks  registered  on  the  widget  with  xtAddEvent- 
Handler,  as  well  as  event  masks  registered  as  a  result  of  translations  and  accelerators 
installed  on  the  widget 

A  Graphics  Context.  A  GC  is  a  pointer  to  a  structure  that  contains  a  copy  of  the  settings 
in  a  server  resource.  The  server  resource,  in  turn,  contains  information  about  how  to 
interpret  a  graphics  primitive.  A  pointer  to  a  structure  of  this  type  is  returned  by  the  Xlib 
call  XGreateGC  or  the  Xt  call  xtGetGC.  (The  latter  call  does  client-side  caching  of 
GCs  to  reduce  the  number  of  identical  GCs  that  are  created.)  GCs  are  used  by  all  Xlib 
drawing  calls.  The  members  of  this  structure  should  not  be  accessed  directly.  Values  can 
be  changed  by  passing  an  XGCValues  structure  to  XtGetGC  or  the  Xlib  XCreateGC 
or  XChangeGC.  Values  can  be  read  with  XGetGCValues. 

Opaque 

As  its  name  implies,  a  typedef  designed  for  portability,  whose  contents  are  not  to  be 
used. 

Position 

A  typedef  from  <X11  /Intrinsic. h>  used  to  specify  x  and  y  coordinates.  The  Position 
data  type  was  introduced  in  R3  to  increase  portability.  R2  applications  that  specified 
coordinates  as  int  should  use  Position  instead. 

Region 

An  arbitrary  set  of  pixels  on  the  screen,  actually  implemented  as  a  linked  list  of  rectan 
gles.  Usually,  a  region  is  either  a  rectangular  area,  several  overlapping  or  adjacent  rec 
tangular  areas,  or  a  general  polygon.  A  Region  is  actually  a  typedef  from 
<Xll/Xutil.h>  pointing  to  an  internal  data  structure  called  an  _XRegion.  There  are  a 
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number  of  Xlib  functions  for  creating  and  manipulating  regions;  the  members  of  the 
structure  should  not  be  accessed  directly.  For  more  information,  see  Volume  Two,  Xlib 
Reference  Manual.  In  Xt,  the  only  use  is  in  the  call  XtAddExposureToRegion. 

Screen 

A  structure  that  describes  the  characteristics  of  a  screen  (one  or  more  of  which  make  up  a 
display).  A  pointer  to  a  list  of  these  structures  is  a  member  of  the  Di  spl  ay  structure.  A 
pointer  to  a  structure  of  this  type  is  returned  by  Xt  Screen  and  XGetwindow- 
Att  ributes.  Xlib  Macros  are  provided  to  access  most  members  of  this  structure. 

typedef  struct  { 

XExtData  *ext_data;        /*  hook  for  extension  to  hang  data  */ 

struct  _XDisplay  *display;/*  back  pointer  to  display  structure  */ 

Window  root;  /*  root  window  ID  */ 

int  width,  height;         /*  width  and  height  of  screen  */ 

int  mwidth,  mheight;       /*  width  and  height  of   in  millimeters  */ 

int  ndepths;  /*  number  of  depths  possible  */ 

Depth  *depths;  /*  list  of  allowable  depths  on  the  screen  */ 

int  root_depth;  /*  bits  per  pixel  */ 

Visual  *root_visual;       /*  root  visual  */ 

GC  default_gc;  /*  GC  for  the  root  root  visual  */ 

Colormap  cmap;  /*  default  colormap  */ 

unsigned  long  white_pixel; 

unsigned  long  black_pixel; /*  white  and  black  pixel  values  */ 

int  max_maps,  min_maps;    /*  max  and  min  colormaps  */ 

int  backing_store;         /*  Never,  WhenMapped,  Always  */ 

Bool  save_unders; 

long  root_input_mask;      /*  initial  root  input  mask  */ 

}  Screen; 

The  Xt  Screen  macro  can  be  used  in  Xt  to  return  the  current  screen. 

String 

A  typedef  for  cha  r   * 

Substitution 

A  structure  used  in  xtFindFile  and  xtResolvePathname  to  specify  substitution 
characters.  In  the  path  argument  to  XtFindFile,  each  character  prefixed  by  a  per 
cent  sign  (%)  is  compared  to  the  match  member  of  a  Substitution,  and  if  found,  is 
replaced  with  the  string  in  the  substitution  member  of  the  same  structure.  This 
allows  for  operating-system-independent  filename  searches,  where  substitutions  can 
identify  possible  pathname  separators. 

It  is  defined  as  follows: 

typedef   struct    { 

char  match;  /*    character  to  match    */ 

String   substitution;  /*    string   to   substitute    */ 

}    SubstitutionRec,    *Substitution; 

SubstitutionRec 
See  Substitution. 

Time 

An  unsigned  long  value  containing  a  time  value  in  milliseconds.  The  constant 
CurrentTime  is  interpreted  as  the  time  in  milliseconds  since  the  server  was  started. 
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The  Time  data  type  is  used  in  event  structures  and  as  an  argument  to  xtAppAdd- 
TimeOut. 

Visual 

A  structure  that  defines  a  way  of  using  color  resources  on  a  particular  screen. 

Widget 

A  structure  returned  by  calls  to  create  a  widget,  such  as  xtApplnitialize,  xt- 
CreateWidget,  XtCreateManagedWidget,  and  XtCreatePopupShell. 
The  members  of  this  structure  should  not  be  accessed  directly  from  applications;  they 
should  regard  it  as  an  opaque  pointer.  Type  widget  is  actually  a  pointer  to  a  widget 
instance  structure.  Widget  code  accesses  instance  variables  from  this  structure. 

WidgetClass 

A  pointer  to  the  widget  class  structure,  used  to  identify  the  widget  class  in  various  Xt 
calls  that  create  widgets  or  that  return  information  about  widgets.  Widget  class  names 
have  the  form  nameffidget Class,  with  the  exception  of  the  widget-precursor  classes, 
Object  and  RectObj,  which  have  the  class  pointers  objectClass  and  rect- 
Ob  j  C 1  a  s  s ,  respectively . 

WidgetList 

A  pointer  to  a  list  of  widgets,  used  in  calls  to  xtManageChildren  and  xt- 
UnManageChildren. 

Window 

A  resource  maintained  by  the  server,  and  known  on  the  client  side  only  by  an  integer  ID. 
In  Xt,  a  widget's  window  can  be  returned  by  the  xtwindow  macro.  Given  the  window, 
the  corresponding  widget  can  be  returned  by  XtwindowToWidget. 

XEvent 

A  union  of  all  thirty  event  structures.  The  first  member  is  always  the  type,  so  it  is  pos 
sible  to  branch  on  the  type,  and  do  event-specific  processing  in  each  branch.  For  more 
information  on  the  individual  event  structures,  see  Appendix  C,  Event  Reference. 

XGCValues 

A  structure  defined  in  <XlllXlib.h>  that  is  used  to  set  the  values  in  a  Graphics  Context 
using  the  XtGetGC  function,  or  the  Xlib  functions  XCreateGC,  XChangeGC,  or 
XGetGCValues. 


typedef  struct  { 
int  function; 
unsigned  long  plane_mask; 
unsigned  long  foreground; 
unsigned  long  background; 
int  line_width; 
int  line  style; 


/*  logical  operation  */ 


int  cap_style; 

int  join_style, 
int  fill_style, 

int  fill_rule; 
int  arc  mode; 


/*  plane  mask  */ 
/*  foreground  pixel  */ 
/*  background  pixel  */ 
/*  line  width  */ 
/*  LineSolid,  LineOnOf fDash, 

LineDoubleDash  */ 
/*  CapNotLast,  CapButt, 

CapRound,  CapPro jecting  */ 
/*  JoinMiter,  JoinRound,  JoinBevel  */ 
/*  FillSolid,  FillTiled, 

FillStippled,  FillOpaqueStippled  */ 
/*  EvenOddRule,  WindingRule  */ 
/*  ArcChord,  ArcPieSlice  */ 
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Pixmap  tile;        / 
Pixmap  stipple;     /: 
int  ts_x_origin;    / 
int  ts_y_origin; 
Font  font; 
int  subwindow_mode; 
Bool  graphics_exposures; 
int  clip_x_origin; 
int  clip_y_origin; 
Pixmap  clip_mask; 

int  dash_of f set; 
char  dashes; 
XGCValues; 


pixmap  for  tiling  operations  */ 
1  plane  pixmap  for  stippling  */ 
offset  for  tile  or  stipple  operations  */ 


/*  default  text  font  for  text  operations  */ 
/*  ClipByChildren,  Includelnf eriors  */ 
/*  should  exposures  be  generated?  */ 
/*  origin  for  clipping  */ 

/*  bitmap  clipping;  other  calls 

for  rects  */ 
/*  patterned/dashed  line  information  */ 


For  more  information  on  the  meaning  and  use  of  each  of  the  members,  see  Chapter  5,  The 
Graphics  Context,  in  Volume  One,  Xlib  Programming  Manual.  The  second  argument  of 
xtGetGC  is  a  mask  that  specifies  which  members  of  the  structure  are  being  set.  See 
xtGCMask  below  for  details. 

XnnDatabase 

A  pointer  to  an  internal  resource  manager  datatype.  Members  of  this  structure  should  not 
be  accessed  directly.  An  XrmDatabase  can  be  returned  by  the  Xt  calls  XtDatabase 
(a  resource  database)  or  xtGetErrorDatabase  (an  error  message  database). 

XrznOpt  i  onDe  s  cLi  s  t 

A  structure  used  to  define  command  line  options,  passed  to  xtAppinitialize,  xt- 
Displaylnitialize,  or  XtOpenDisplay.  The  structure  is  defined  as  follows  in 
<X1 1  IXresource.h>: 


typedef  struct 
char 
char 


*option;    /*  Option  abbreviation  in  argv  */ 
* specif ier; /*  Resource  specifier  */ 


XrmOptionKind  argKind;    /• 
caddr  t        value;      /' 


Which  style  of  option  it  is  */ 

Val  to  provide  if  Xrmopt ionNoArg  */ 


}  XrmOptionDescRec,  *XrmOptionDescList; 

The  value  for  the  argKind  element  is  specified  by  one  of  the  following  enumerated  val 
ues,  defined  in  the  same  file: 


typedef  enum  { 

XrmoptionNoArg,  /* 
XrmoptionlsArg,  /* 
Xrmopt ionStickyArg,  /* 


Xrmopt  ionSepAr g , 
Xrmopt ionRes Arg, 
Xrmopt ionSkipArg, 


/* 
/* 
/* 


Xrmopt ionSkipNArgs  /* 

Xrmopt ionSkipLine   /* 
}  XrmOptionKind; 


Value  specified  in  OptionDescRec. value  */ 
Value  is  the  option  string  itself  */ 
Value  immediately  follows  option  */ 
Value  is  next  argument  in  argv  */ 
Resource  and  value  in  next  arg  in  argv  */ 
Ignore  this  opt  and  next  arg  in  argv  */ 
Ignore  this  option  and  the  next 
OptionDescRec .value  arguments  in  argv  */ 
Ignore  this  opt  and  rest  of  argv  */ 


XrmOptionDescRec 

See  XrmOptionDescList. 

XrmOptionKind 

See  XrmOptionDescList. 
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XrmValue 

A  structure  defined  in  <Xll/Xresource.h>,  used  in  xtConvert  and  other  resource  con 
version  routines. 

typedef   struct    { 

unsigned   int  size; 

caddr_t  addr; 

}    XrmValue,    *XrmValuePtr; 

XrmValuePtr 
See  XrmValue. 

XtAccelerators 

A  pointer  to  an  opaque  internal  type,  a  compiled  accelerator  table.  A  pointer  to  an  Xt 
Accelerators  structure  is  returned  by  a  call  to  XtParseAcceleratorTable. 
Usually,  the  compiled  accelerator  table  is  produced  automatically  by  resource  conversion 
of  a  string  accelerator  table  stored  in  a  resource  file. 

XtActionHookld 

An  opaque  identifier  returned  by  a  call  to  xtAppAddActionHook,  and  used  there 
after  to  refer  to  a  particular  action  hook  procedure. 

XtActionHookProc 

The  typedef  for  an  action  hook  procedure.  See  xtActionHookProc(2)  for  details. 

XtActionList 

A  typedef  for  _xtActionsRec,  defined  as  follows  in  <X1  II Intrinsic. h>\ 

typedef  struct  _XtActionsRec  *XtActionList; 

typedef  struct  _XtActionsRec{ 

String    string; 

XtActionProc  proc; 
}  XtActionsRec; 

Actions  are  added  by  calls  to  xtAddActions  or  xtAppAddActions.  By  conven 
tion,  the  string  and  the  function  name  are  identical,  except  that  the  function  name  begins 
with  an  upper-case  letter,  as  in  the  example: 

static   XtActionsRec   two_quits[]    =    { 
{"confirm",    Confirm}, 
{"quit",    Quit}, 

}; 

This  mapping  from  strings  to  function  pointers  is  necessary  to  allow  translation  tables  to 
be  specified  in  resource  files,  which  are  made  up  entirely  of  strings. 

XtActionProc 

The  typedef  for  an  action  procedure.  See  xtActionProc(2)  for  details. 

XtActionsRec 

See  XtActionList. 

XtAddressMode 

An  enumerated  type  that  specifies  the  possible  values  for  the  address_mode  field  of 
an  XtConvertArgRec.  See  xtConvertArgList  below  for  details. 
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XtAppContext 

A  pointer  to  an  internal  structure  used  to  hold  data  specific  to  a  particular  application 
context.  An  xtAppContext  can  be  returned  by  a  call  to  xtCreate- 
ApplicationContext  or  XtAppInitialize.  The  application  context  being 
used  by  a  widget  can  be  returned  by  xtwidgetToApplicationContext.  The  Xt 
routines  that  use  a  default  application  context  are  now  superseded;  almost  all  routines  for 
handling  explicit  application  contexts  have  names  containing  the  string  App. 

XtArgVal 

SeeArgList. 

XtCacheRef 

An  opaque  converter  cache  identifier  returned  in  the  cache_ref_return  argument 
of  xtCallConverter.  The  identifier  reference  count  is  decremented  whenever  the 
cached  resource  is  released  by  a  client. 

XtCacheType 

Identifies  the  type  and  amount  of  type  converter  caching  to  be  used;  specified  in  calls  to 
XtAppSetTypeConverter  and  XtSetTypeConverter.  Possible  values  are 
given  by  the  following  symbols: 

fdefine  XtCacheNone       0x001  /*  never  cache;  always  call  converter  */ 
fdefine  XtCacheAll        0x002  /*  reuse  results  of  previous  conversions 

if  they  match  */ 
fdefine  XtCacheByDisplay  0x003  /*  reuse  results,  but  remove  value 

from  cache  if  display  is  closed  */ 
fdefine  XtCacheRefCount   0x100  /*  OR  with  above  values  to  keep  a 

count  of  times  a  conversion  is  used. 

When  count  falls  to  zero,  remove 

conversion  from  cache  */ 

XtCallbackList 

A  structure  defined  as  follows  in  <X11  /Intrinsic. h>: 

XtCallbackProc   callback; 
XtPointer        closure; 
}  XtCallbackRec,  *XtCallbackList; 

An  XtCallbackList  is  statically  defined  just  after  the  callback  function  itself  is 
declared  or  defined.  Then  the  callback  list  is  used  to  set  a  callback  resource  with  any  of 
the  calls  that  set  resources,  including  xtCreateWidget.  In  most  documentation,  the 
closure  member  is  referred  to  as  client_data.  In  application  code,  when  xt- 
AddCallback  and  xtRemoveCallback  are  used,  an  XtCallbackList  is  not 
required. 

XtCallbackProc 

The  typedef  for  callback  functions.  See  xtCallbackProc(2)  for  details. 

XtCallbackRec 

See  XtCallbackList. 

XtCallbackStatus 

An  enumerated  type  that  defines  the  return  values  from  xtHasCallbacks: 
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typedef   enum    { 

XtCallbackNoList,       /*    Callback    resource    doesn't    exist    */ 
XtCallbackHasNone,    /*    Resource   exists,    but    no   callbacks    on    it    */ 
XtCallbackHasSome      /*    Resource   exists,    and   callbacks 

are    registered   for    it    */ 

}    XtCallbackStatus; 

XtCancelConvertSelectionProc 

The  typedef  for  a  cancel  selection  conversion  procedure  registered  by  a  call  to  xtOwn- 
Selectionlncremental.  See  XtCancelConvertSelectionProc(2)  for 
details. 

XtCaseProc 

The  typedef  for  the  case  conversion  procedure  registered  by  a  call  to  xtRegister- 
CaseConverter.  SeextCaseProc(2)  for  details. 

XtConvertArgLi s t 

A  structure  used  in  calls  to  XtAddConverter,  XtSetTypeConverter,  and  Xt- 
AppSetTypeConverter  to  specify  how  the  converter  will  get  the  arguments  neces 
sary  to  perform  the  conversion.  The  structure  is  defined  as  follows  in  <X11  /Intrinsic. h>: 

typedef  struct  { 

XtAddressMode  address_mode; 

XtPointer  address_id; 

Cardinal  size; 

}  XtConvertArgRec,  *XtConvertArgList; 

The  enumerated  type  XtAddressMode  specifies  the  possible  values  for  the 
address_mode  field,  which  controls  how  the  address_id  field  should  be  inter 
preted. 

typedef   enum    { 

XtAddress,  /*    address    */ 

XtBaseOffset,  /*    offset    */ 

Xtlmmediate,  /*    constant    */ 

XtResourceString,  /*    resource   name    string    */ 

XtResourceQuark  /*    resource   name   quark    */ 

XtWidgetBaseOffset,  /*    offset    from   ancestor    */ 

XtProcedureArg  /*    procedure    to   call    */ 
}    XtAddressMode; 

By  specifying  the  address  mode  as  XtBaseOffset  or  XtWidgetBaseOffset  you 
can  use  XtOf  f  set  or  xtOf  f  setOf  to  find  the  appropriate  widget  resource,  much  as 
you  do  in  a  resource  list. 

XtConvertArgRec 

See  XtConvertArgList. 

XtConverter 

The  typedef  for  old-style  resource  converters.  See  xtConverter(2)  for  details. 

XtConvertSelectionlncrProc 

The  typedef  for  the  incremental  selection  conversion  procedure.  See  xt Convert - 
SelectionIncrProc(2)  for  details. 
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XtConvert Selection? roc 

The  typedef  for  the  selection  conversion  procedure  registered  by  a  call  to  xtOwn- 
Selection.  See  XtConvertSelectionProc(2)  for  details. 

XtDestructor 

The  typedef  for  a  resource-cache-freeing  procedure  registered  by  a  call  to  xtAppSet- 
TypeConverter  or  XtSetTypeConverter.  See  XtDestructor(2)  for 
details. 

XtEnum 

A  datum  large  enough  to  encode  at  least  128  distinct  values,  two  of  which  are  the  sym 
bolic  values  True  and  False. 

XtErrorHandler 

The  typedef  for  low-level  error  or  warning  handlers.  See  xtErrorHandler(2)  for 
details. 

XtErrorMsgHandler 

The  typedef  for  high-level  error  or  warning  message  handlers.  See  xtErrorMsg- 
Handler(2)  for  details. 

Xt Event Handler 

The  typedef  for  event  handlers.  See  xtEventHandler(2)  for  details. 

XtFilePredicate 

The  prototype  for  a  filename  evaluation  procedure  registered  by  the  call  to  xt Find- 
File  orXtResolvePathname.  See  XtFilePredicate(2)  for  details. 

XtGCMasJc 

A  mask  used  in  calls  to  xtGetGC  that  indicates  which  fields  in  the  XGCValues  struc 
ture  are  to  be  used.  The  mask  consists  of  a  bitwise  OR  of  the  following  symbols: 


Member 

Mask 

Default 

function 

GCFunction 

GXcopy 

plane  mask 

GCPlaneMask 

alli's 

foreground 

GCForeground 

0 

background 

GCBackground 

i 

line  width 

GCLineWidth 

0 

line  style 

GCLineStyle 

LineSolid 

cap  style 

GCCapStyle 

CapButt 

join  style 

GCJoinStyle 

JoinMiter 

fill_style 

GCFillStyle 

FillSolid 

fill_rule 

GCFillRule 

EvenOddRule 

tile 

GCTile 

pixmap  filled  with 

foreground  pixel 

stipple 

GCStipple 

pixmap  filled  with  1's 

ts  x  origin 

GCTileStipXOrigin 

0 

ts  y  origin 

GCTileStipYOrigin 

0 

font 

GCFont 

(implementation 

dependent) 

subwindow  mode 

GCSubwindowMode 

ClipByChildren 
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Member 

graphics_exposures 

clip_x_origin 

c 1 ip_y_or  i  g  i  n 

clip_mask 

dash_of f set 

dashes 

arc  mode 


Mask 

GCGraphicsExposures 

GCClipXOrigin 

GCClipYOrigin 

GCClipMask 

GCDashOffset 

GCDashList 

GCArcMode 


Default 

TRUE 

0 

0 

None 

0 

4  (i.e.,  the  list  [4, 4]) 

ArcPieSlice 


Xt Geomet ryMa s Jc 

See  XtWidget Geometry. 

Xt Geometry Result 

An  enumerated  type  used  as  the  return  value  of  the  xtQueryGeometry,  xtMake- 
GeometryRequest,  and  XtMakeResizeRequest  functions.  It  is  defined  as  fol 
lows  in  <XlllIntrinsic.h>: 


typedef  enum   { 

XtGeometryYes,  /< 

XtGeometryNo,  /' 

XtGeometryAlmost,  /; 

XtGeometryDone  /' 

}  XtGeometryResult; 


Request  accepted  */ 

Request  denied  */ 

Request  denied  but  willing  to  take  reply  */ 

Request  accepted  and  done  */ 


XtGrabKind 

An  enumerated  type  used  in  calls  to  xt Popup  to  specify  the  nature  of  the  grab  to  be 
asserted  by  the  pop-up  widget 

typedef  enum  { 

XtGrabNone, 

XtGrabNonexclusive, 

XtGrabExclusive 
}  XtGrabKind; 

An  exclusive  grab  constrains  input  to  the  widget  actually  making  the  grab  (the  latest 
widget  in  a  pop-up  cascade),  while  a  non-exclusive  grab  allows  input  to  any  widget  in  the 
cascade. 

Xt Input Callback? roc 

The  typedef  for  the  procedure  registered  by  a  call  to  xtAppAddinput.  See  xt- 
InputCallbackProc(2)  for  details. 

Xt Input Id 

A  unique  ID  returned  by  a  call  to  XtAppAddinput;  used  to  remove  an  input  source 
with  Xt  Remove  Input. 

XtlnputMask 

A  mask  used  in  calls  to  xtProcessEvent  to  indicate  which  types  of  events  should  be 
processed.  This  mask  is  made  up  of  a  bitwise  OR  of  the  following  symbols  defined  in 
<X11  /Intrinsic.  h>: 
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xt  iMXEvent  Process  X  Events. 

xtiMTimer  Process  timeouts  registered  with  xtAddTimeout . 

xtiMAlternateinput  Process  alternate  input  sources  registered  with  xtAddinput . 

x 1 1 MAI  l  Process  all  three  types  of  events. 

An  xtlnputMask  is  returned  by  xtPending  to  indicate  what  type  of  events  are  in 
the  event  queue.  Don't  confuse  these  values  with  XtlnputNoneMask,  xtlnput- 
WriteMask,  XtlnputReadMask,  and  XtlnputExceptMask,  which  are  used  in 
calls  to  XtAddinput  to  indicate  whether  the  file  should  be  monitored  for  reads,  writes, 
or  exception  conditions. 

Xt Interval Id 

A  unique  ID  returned  by  a  call  to  xtAppAddTimeout;  used  to  remove  a  timeout  with 
XtRemoveTimeout.  Remember  that  timeouts  are  automatically  removed  when  the 
time  expires. 

XtKeyProc 

The  prototype  for  the  keycode-to-keysym  translation  procedure  registered  in  a  call  to 
xtSetKeyTranslator.  The  default  key  translator  is  the  Xt  Intrinsics  function  xt- 
TranslateKey.  See  XtKeyProc(2)  for  more  details. 

XtListPosition 

An  enumerated  type  used  in  calls  to  Xt  Insert  Event  Handler  and  xt Insert - 
RawEvent Handler  to  specify  when  the  event  handler  is  to  be  called  relative  to  other 
previously  registered  handlers.  It  is  defined  as  follows: 

typedef   enum    { XtListHead,    XtListTail }    XtListPosition; 

XtLoseSelectionlncrProc 

The  prototype  for  the  lose  selection  procedure  registered  by  a  call  to  xtOwn- 
Selectionlncremental.  This  optional  procedure  is  called  by  Xt  to  inform  the 
specified  widget  that  it  has  lost  the  given  selection.  See  XtLoseSelectionlncr 
Proc  for  more  details. 

XtLoseSelectionProc 

The  typedef  for  the  lose  selection  procedure  registered  by  a  call  to  xtOwnSelection. 
See  XtLoseSelectionProc(2)  for  details. 

XtPointer 

A  datum  large  enough  to  contain  the  largest  of  a  char*,  int*,  function  pointer,  struc 
ture  pointer,  or  long  value.  A  pointer  to  any  type  or  function,  or  a  long,  may  be  converted 
to  an  XtPointer  and  back  again  and  the  result  will  compare  equal  to  the  original 
value.  In  ANSI  C  environments,  it  is  expected  that  XtPointer  will  be  defined  as 
void. 

XtPopdownlD 

A  structure  used  by  the  built-in  callback  function  XtCallbackPopdown.  This  struc 
ture  contains  the  Shell  widget  that  is  being  popped  down  and  the  enabling  widget  that 
originally  popped  up  the  shell.  XtPopdownlD  is  defined  as  follows  in  <Xll/Intrin- 
sics.h>: 
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typedef  struct  { 

Widget   shell_widget; 

Widget   enable_widget ; 
}  XtPopdownlDRec,  *XtPopdownID; 

Xt Request Id 

An  opaque  identifier  for  a  particular  incremental  selection  transfer  request 

XtResource 

See  xtResourceList  below. 

XtResourceList 

A  structure  used  to  declare  widget  or  application  resources,  and  to  retrieve  the  current 
value  of  resources  using  XtGetSubresources,  xtGetSubvalues,  or  xtGet- 
ResourceList.  It  is  defined  as  follows  in  <X1  II Intrinsic. h>: 

typedef    struct   _XtResource    { 

String   resource_name;  /*  specify   using   XtN    symbol    */ 

String   resource_class;  /*  specify   using   XtC    symbol    */ 

String   resource_type;  /*  actual    data    type   of   variable    */ 

Cardinal    resource_size;  /*  specify  using   sizeof()    */ 

Cardinal   resource_of f set;  /*  specify  using  XtOffsetO    */ 

String   default_type;  /*  will   be    conv'ted   to   resource_type    */ 

XtPointer   def ault_addr;  /*  address   of   default    value    */ 

}    XtResource,     *XtResourceList; 

See  Chapter  9,  Resource  Management  and  Type  Conversion,  in  Volume  Four,  X  Toolkit 
Intrinsics  Programming  Manual,  for  a  detailed  description  of  the  XtResource  struc 
ture. 

XtSelectionCallbackProc 

The  typedef  for  the  selection  callback  procedure  registered  by  a  call  to  xtGet- 
SelectionValue  or  XtGetSelectionValues.  See  XtSelection- 
CallbackProc(2)  for  details. 

XtSelectionDonelncrProc 

The  prototype  for  the  selection  completion  procedure  registered  by  a  call  to  xtOwn- 
Selectionlncremental.  See  XtSelectionDonelncrProc  (2)  for  details. 

XtSelectionDoneProc 

The  typedef  for  the  selection  completion  procedure  registered  by  a  call  to  xtOwn- 
Selection.  See  XtSelectionDoneProc(2)  for  details. 

Xt Time  rCallbackP roc 

The  typedef  for  the  procedure  to  be  invoked  after  a  timeout  registered  by  a  call  to  Xt  - 
AppAddTimeout.  See  XtTimerCallbackProc(2)  for  details. 

XtTranslations 

A  pointer  to  an  opaque  internal  type,  a  compiled  translation  table.  A  pointer  to  an  Xt  - 
Translations  structure  is  returned  by  a  call  to  XtParseTranslationTable. 
Usually,  the  compiled  translation  table  is  produced  automatically  by  resource  conversion 
of  a  string  translation  table  stored  in  a  resource  file. 
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XtTypeConverter 

The  prototype  for  new-style  type  converters  as  of  R4.  See  xtConverterfor  a  descrip 
tion  of  the  obsolete  R3  interface.  The  new  interface  provides  more  information  to  con 
verters,  supports  conversion  cache  cleanup  with  resource  reference  counting,  and  allows 
additional  procedures  to  be  declared  to  free  resources.  See  XtTypeConverter  (2)  for 
details. 

XtValueMask 

A  mask  used  in  calls  to  xtCreateWindow  to  indicate  which  window  attribute  fields  to 
use. 

XtWidgetGeoxnetry 

A  structure  used  to  pass  in  and  return  data  about  widget  geometry  in  calls  to  x  t  Query - 
Geometry  and  XtMakeGeometryRequest.  It  is  defined  as  follows  in 
<X1  II Intrinsic. h>: 

typedef  struct  { 

XtGeometryMask  request_mode; 

Position  x,  y; 

Dimension  width,  height,  border_width; 

Widget  sibling; 

int  stack_mode; 
}  XtWidgetGeometry; 

The  request_mode  field  specifies  which  of  the  other  fields  are  to  be  used,  or  (for 
returned  structures)  contain  valid  values.  It  is  made  up  of  a  bitwise  OR  of  the  following 
symbols  defined  in  <Xll/X.h>: 

#define   CWX  (1«0) 

tdefine    CWY  (1«1) 

tdefine   CWWidth  (1«2) 

f define   CWHeight  (1«3) 

f define    CWBorderWidth  (1«4) 

fdefine   CWSibling  (1«5) 

f  define   CWStackMode  (1«6) 

plus  the  following  symbol  from  <Xll/Intrinsic.h>: 
Idefine   XtCWQueryOnly  (1«7) 

which  means  that  this  call  is  a  query  only,  and  none  of  the  values  should  be  used;  the 
return  value  should  show  what  would  happen  if  the  geometry  request  were  made.  (In 
case  you're  wondering,  the  CW  prefix  stands  for  "ConfigureWindow" —  these  symbols 
are  also  used  by  the  Xlib  XGonf  igurewindow  call.) 

The  stack_mode  field  specifies  the  relationship  between  the  current  widget  and  a 
sibling  widget  specified  in  the  same  call.  It  is  specified  using  one  of  the  following 
symbols  defined  in  <Xll/X.h>: 

Below  Place  widget  below  sibling  or  on  bottom  of  stack  if  no  sibling. 

Top  i  f  Place  widget  on  top  of  stack  if  obscured. 

Bottom  I  f  Place  widget  on  botton  if  it  obscures  sibling. 
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opposite  If  sibling  occludes  the  widget,  put  widget  on  top  of  stack,  but  if 

widget  occludes  sibling,  put  widget  on  the  bottom. 

plus  the  following  symbol  from  <X1  II Intrinsic. h>: 

xtSMDontchange     Don't  change  the  stacking  order. 

If  no  sibling  widget  is  specified  in  the  call,  the  stacking  order  is  relative  to  any  sibling. 

XtWorkProc 

The  typedef  for  the  work  procedure  registered  by  a  call  to  XtAppAddWorkProc.  See 
XtWorkProc(2)  for  details. 

XtWorkProcId 

The  unique  identifier  returned  by  a  call  to  XtAppAddWorkProc  and  used  as  an  argu 
ment  in  XtRemoveWorkProc. 
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Event  Reference 


This  appendix  describes  each  event  in  detail.  It  covers  how  the  event  is  selected,  what  trans 
lation  table  symbols  are  valid  for  each  event  type,  when  each  event  occurs,  the  information 
contained  in  each  event  structure,  and  the  side  effects  of  the  event,  if  any.  Each  event  is 
described  on  a  separate  reference  page. 

Table  C-l  lists  each  event  mask,  its  associated  event  types,  and  the  associated  structure  defi 
nition.  See  Chapter  8,  Events,  in  Volume  One,  Xlib  Programming  Manual,  for  more  infor 
mation  on  events.  See  also  Chapter  7,  Events,  Translations,  and  Accelerators,  in  Volume 
Four,  X  Toolkit  Intrinsics  Programming  Manual. 


Table  C-1.  Event  Masks,  Event  Types,  and  Event  Structures 


Event  Mask 


Event  Type 


Event  Structure 


KeyPressMask 

KeyReleaseMask 

ButtonPressMask 

ButtonReleaseMask 

Owner GrabButtonMask 

KeymapStateMask 

PointerMotionMask 

Point erMotionHintMask 

ButtonMotionMask 

ButtonlMotionMask 

Button2MotionMask 

ButtonSMotionMask 

Button4MotionMask 

ButtonSMotionMask 

EnterWindowMask 
LeaveWindowMask 
FocusChangeMask 


KeyPress 
KeyRelease 
ButtonPress 
But tonRe lease 

n/a 

KeymapNot  i  f y 
MotionNotify 


XKeyPressedEvent 
XKeyReleasedEvent 
XButtonPressedEvent 
XButtonReleasedEvent 

n/a 

XKeymapEvent 
XPointerMovedEvent 


EnterNotify 
LeaveNotify 
Focusln 


XEnterWindowEvent 
XLeaveWindowEvent 
XFocusInEvent 
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Table  C-1.  Event  Masks,  Event  Types,  and  Event  Structures  (continued) 


Event  Mask 

Event  Type 

Event  Structure 

FocusOut 

XFocusOutEvent 

ExposureMask 

Expose 

XExposeEvent 

(selected  in  GC  by 

GraphicsExpose 

XGraphicsExposeEvent 

graphics_expose  member) 

NoExpose 

XNoExposeEvent 

ColormapChangeMask 

ColormapNotify 

XColormapEvent 

PropertyChangeMask 

PropertyNotify 

XPropertyEvent 

VisibilityChangeMask 

VisibilityNotify 

XVisibilityEvent 

ResizeRedirectMask 

ResizeRequest 

XResizeRequestEvent 

StructureNotifyMask 

CirculateNotify 

XCirculateEvent 

ConfigureNotify 

XConfigureEvent 

DestroyNotify 

XDestroyWindowEvent 

GravityNotify 

XGravityEvent 

MapNotify 

XMapEvent 

ReparentNotify 

XReparent  Event 

UnmapNotify 

XUnmapEvent 

SubstructureNotifyMask 

CirculateNotify 

XCirculateEvent 

ConfigureNotify 

XConfigureEvent 

CreateNotify 

XCreateWindowEvent 

DestroyNotify 

XDestroyWindowEvent 

GravityNotify 

XGravityEvent 

MapNotify 

XMapEvent 

ReparentNotify 

XReparentEvent  , 

UnmapNotify 

XUnmapEvent 

SubstructureRedirectMask 

CirculateRequest 

XCirculateRequest  Event 

Conf  igureRequest 

XConf  igureRequest  Event 

MapRequest 

XMapRequestEvent 

(always  selected) 

MappingNotify 

XMappingEvent 

(always  selected) 

ClientMessage 

XClientMessageEvent 

(always  selected) 

Select  ionClear 

XSetSelectClearEvent 

(always  selected) 

SelectionNotify 

XSelectionEvent 

(always  selected) 

SelectionRequest 

XSelectionRequest  Event 
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Meaning  of  Common  Structure  Elements 

Example  C-l  shows  the  XEvent  union  and  a  simple  event  structure  that  is  one  member  of 
the  union.  Several  of  the  members  of  this  structure  are  present  in  nearly  every  event  struc 
ture.  They  are  described  here  before  we  go  into  the  event-specific  members  (see  also  Section 
8.2.2  in  Volume  One,  Xlib  Programming  Manual). 

Example  C-1.  XEvent  union  and  XAny Event  structure 


typedef  union  _XEvent    { 

int   type; 

XAnyEvent 

XButtonEvent 

XCirculateEvent 

XCirculateRequestEvent 

XClientMessageEvent 

XColormapEvent 

XConf igureEvent 

XConf igureRequestEvent 

XCreateWindowEvent 

XDestroyWindowEvent 

XCrossingEvent 

XExposeEvent 

XFocusChangeEvent 

XNoExposeEvent 

XGraphicsExposeEvent 

XGravityEvent 

XKeymapEvent 

XKeyEvent 

XMapEvent 

XUnmapEvent 

XMappingEvent 

XMapRequest Event 

XMot  ionE vent 

XPropertyEvent 

XRepar en t Event 

XResizeRequestEvent 

XSelectionClearEvent 

XSelect ionE vent 

XSelectionRequest Event 

XVisibilityEvent 

long 
}    XEvent; 

typedef  struct  { 
int  type; 

unsigned  long  serial; 
Bool  send_event; 
Display  *display; 
Window  window; 

}  XAnyEvent; 


/*  must  not  be  changed;  first  member  */ 

xany; 

xbutton; 

xcirculate; 

xcirculaterequest; 

xclient; 

xcolormap; 

xconfigure; 

xconfigurerequest; 

xcreate window; 

xde s troy window; 

xcrossing; 

xexpose; 

xfocus; 

xnoexpose; 

xgraphicsexpose ; 

xgravity; 

xkeymap; 

xkey; 

xmap; 

xunmap; 

xmapping; 

xmaprequest ; 

xmotion; 

xproperty; 

xreparent; 

xresizerequest ; 

xselectionclear; 

xselection; 

xselectionrequest; 

xvisibility; 

pad [24]; 


/*  t  of  last  request  processed  by  server  */ 

/*  TRUE  if  this  came  from  SendEvent  request  */ 

/*  display  the  event  was  read  from  */ 

/*  window  on  which  event  was  requested  in 

*  event  mask  */ 
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The  first  member  of  the  XEvent  union  is  the  type  of  event  When  an  event  is  received  (with 
XNextEvent,  for  example),  the  application  checks  the  type  member  in  the  XEvent 
union.  Then  the  specific  event  type  is  known  and  the  specific  event  structure  (such  as 
xbutton)  is  used  to  access  information  specific  to  that  event  type. 

Before  the  branching  depending  on  the  event  type,  only  the  XEvent  union  is  used.  After 
the  branching,  only  the  event  structure  that  contains  the  specific  information  for  each  event 
type  should  be  used  in  each  branch.  For  example,  if  the  XEvent  union  were  called 
report,  the  report .  xexpose  structure  should  be  used  within  the  branch  for  Expose 
events. 

You'll  notice  that  each  event  structure  also  begins  with  a  type  member.  This  member  is 
rarely  used,  since  it  is  an  identical  copy  of  the  type  member  in  the  XEvent  union. 

Most  event  structures  also  have  a  window  member.  The  only  ones  that  don't  are  selection 
events  (SelectionNotify,  SelectionRequest,  and  SelectionClear)  and 
events  selected  by  the  graphics_exposures  member  of  the  GC  (GraphicsExpose 
and  NoExpose).  The  window  member  indicates  the  event  window  that  selected  and 
received  the  event.  This  is  the  window  where  the  event  arrives  if  it  has  propagated  through 
the  hierarchy  as  described  in  Section  7.2.1,  in  Volume  Four,  X  Toolkit  Intrinsics  Program 
ming  Manual.  One  event  type  may  have  two  different  meanings  to  an  application,  depending 
on  which  window  it  appears  in. 

Many  of  the  event  structures  also  have  a  display  and/or  root  member.  The  display 
member  identifies  the  connection  to  the  server  that  is  active.  The  root  member  indicates 
which  screen  in  the  hierarchy  links  the  window  that  received  the  event  Most  programs  use 
only  a  single  screen  and  therefore  don't  need  to  worry  about  the  root  member.  The  dis 
play  member  can  be  useful  since  you  can  pass  the  display  variable  into  routines  by  simply 
passing  a  pointer  to  the  event  structure,  eliminating  the  need  for  a  separate  display  argument. 

All  event  structures  include  a  serial  member  that  gives  the  number  of  the  last  protocol 
request  processed  by  the  server.  This  is  useful  in  debugging,  since  an  error  can  be  detected 
by  the  server  but  not  reported  to  the  user  (or  programmer)  until  the  next  routine  that  gets  an 
event  That  means  several  routines  may  execute  successfully  after  the  error  occurs.  The  last 
request  processed  often  indicates  the  request  that  contained  the  error. 

All  event  structures  also  include  a  send_event  flag,  which  if  True  indicates  that  the 
event  was  sent  by  xSendEvent  (i.e.,  by  another  client  rather  than  by  the  server). 

The  following  pages  describe  each  event  type  in  detail.  The  events  are  presented  in  alphabet 
ical  order,  each  on  a  separate  page  (except  for  a  few  complementary  pairs  that  are  described 
together).  Each  page  describes  the  circumstances  under  which  the  event  is  generated,  the 
mask  used  to  select  it,  the  structure  itself,  its  members,  and  useful  programming  notes.  Note 
that  the  description  of  the  structure  members  does  not  include  those  members  common  to 
many  structures.  If  you  need  more  information  on  these  members,  please  refer  to  this  intro 
ductory  section. 
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—  x  button 


/         ButtonPress,  ButtonRelease 


When  Generated 

There  are  two  types  of  pointer  button  events:   ButtonPress  and  ButtonRelease.  Both 
contain  the  same  information. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  ButtonPress  or  ButtonRelease  may  be  used,  or  use 
one  of  the  abbreviations  shown  in  the  following  table. 


Abbreviation 


BtnDown 

BtnlDown 

Btn2Down 

BtnSDown 

Btn4Down 

BtnSDown 

BtnUp 

BtnlUp 

Btn2Up 

BtnSUp 

Btn4Up 

BtnSUp 


Description 


Any  pointer  button  pressed 
Pointer  button  1  pressed 
Pointer  button  2  pressed 
Pointer  button  3  pressed 
Pointer  button  4  pressed 
Pointer  button  5  pressed 
Any  pointer  button  released 
Pointer  button  1  released 
Pointer  button  2  released 
Pointer  button  3  released 
Pointer  button  4  released 
Pointer  button  5  released 


Select  With 

May  be  selected  separately,  using  ButtonPressMask  and  ButtonReleaseMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 
XButtonEvent  xbutton; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type;  /' 

unsigned  long  serial;  /' 

Bool  send_event;  /' 

Display  *display;  /' 

Window  window;  /' 

Window  root;  /' 

Window  subwindow;  X1 

Time  time;  /' 

int  x,  y;  /' 

int  x_root,  y_root;  /' 

unsigned  int  state;  /' 

unsigned  int  button;  /' 


of  event  */ 

#  of  last  request  processed  by  server  */ 

TRUE  if  this  came  from  SendEvent  request  */ 

display  the  event  was  read  from  */ 

event  window  it  is  reported  relative  to  */ 

root  window  that  the  event  occurred  under  */ 

child  window  */ 

when  event  occurred,  in  milliseconds  */ 

pointer  coords  relative  to  receiving  window  */ 

coordinates  relative  to  root  */ 

mask  of  all  buttons  and  modifier  keys  */ 

button  that  triggered  event  */ 
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ButtOnPress,   ButtOnRelease  (continued)  xbutton 

Bool   same_screen;  /*   same   screen   flag   */ 

}    XButtonEvent; 

typedef   XButtonEvent  XButtonPressedEvent; 

typedef   XButtonEvent  XButtonReleasedEvent; 

Event  Structure  Members 

subwindow   If  the  source  window  is  the  child  of  the  receiving  window,  then  the  subwindow 
member  is  set  to  the  ID  of  that  child. 

time  The  server  time  when  the  button  event  occurred,  in  milliseconds.    Time  is 

declared  as  unsigned  long,  so  it  wraps  around  when  it  reaches  the  maxi 
mum  value  of  a  32  bit  number  (every  49.7  days). 

x ,    y  If  the  receiving  window  is  on  the  same  screen  as  the  root  window  specified  by 

root,  then  x  and  y  are  the  pointer  coordinates  relative  to  the  receiving  win 
dow's  origin.  Otherwise,  x  and  y  are  zero. 

When  active  button  grabs  and  pointer  grabs  are  in  effect  (see  Volume  One,  Xlib 
Programming  Manual,  Section  9.4  and  Volume  Four,  X  Toolkit  Intrinsics  Pro 
gramming  Manual,  Section  12.2.2)  the  coordinates  relative  to  the  receiving  win 
dow  may  not  be  within  the  window  (they  may  be  negative  or  greater  than  win 
dow  height  or  width). 

x_root,  y_root 

The  pointer  coordinates  relative  to  the  root  window  which  is  an  ancestor  of  the 
event  window.  If  the  pointer  was  on  a  different  screen,  these  are  zero. 

state  The  state  of  all  the  buttons  and  modifier  keys  just  before  the  event,  represented 

by  a  mask  of  the  button  and  modifier  key  symbols:  ButtonlMask,  But- 
ton2Mask,  ButtonSMask,  Button4Mask,  ButtonSMask,  ShiftMask, 
ControlMask,  LockMask,  ModlMask,  Mod2Mask,  ModSMask,  Mod4- 
Mask,  and  ModSMask.  If  a  modifier  key  is  pressed  and  released  when  no  other 
modifier  keys  are  held,  the  ButtonPress  will  have  a  state  member  of  0  and 
the  But tonRe lease  will  have  a  nonzero  state  member  indicating  that  itself 
was  held  just  before  the  event 

button          A  value  indicating  which  button  changed  state  to  trigger  this  event  One  of  the 
constants:  Buttonl,  Button2,  Buttons,  Button4,  or  Buttons. 

same_screen 

Indicates  whether  the  pointer  is  currently  on  the  same  screen  as  this  window. 
This  is  always  TRUE  unless  the  pointer  was  actively  grabbed  before  the  auto 
matic  grab  could  take  place. 

Notes 

Unless  an  active  grab  already  exists,  or  a  passive  grab  on  the  button  combination  that  was 
pressed  already  exists  at  a  higher  level  in  the  hierarchy  than  where  the  ButtonPress 
occurred,  an  automatic  active  grab  of  the  pointer  takes  place  when  a  ButtonPress  occurs. 
Because  of  the  automatic  grab,  the  matching  ButtonRelease  is  sent  to  the  same  application 
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xbutton  (continued)  ButtonPress,  ButtonRelease 

that  received  the  ButtonPress  event  If  OwnerGrabButtonMask  has  been  selected,  the 
ButtonRelease  event  is  delivered  to  the  window  which  contained  the  pointer  when  the  but 
ton  was  released,  as  long  as  that  window  belongs  to  the  same  client  as  the  window  in  which  the 
ButtonPress  event  occurred.  If  the  ButtonRelease  occurs  outside  of  the  client's  win 
dows,  or  OwnerGrabButtonMask  was  not  selected,  the  ButtonRelease  is  delivered  to 
the  window  in  which  the  ButtonPress  occurred.  The  grab  is  terminated  when  all  buttons 
are  released.  During  the  grab,  the  cursor  associated  with  the  grabbing  window  will  track  the 
pointer  anywhere  on  the  screen. 

If  the  application  has  invoked  a  passive  button  grab  on  an  ancestor  of  the  window  in  which  the 
ButtonPress  event  occurs,  then  that  grab  takes  precedence  over  the  automatic  grab,  and  the 
ButtonRelease  will  go  to  that  window,  or  it  will  be  handled  normally  by  that  client  depend 
ing  on  the  owner_events  flag  in  the  XGrabButton  call. 
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CirculateNotify 


X 


•xcirculate — 


When  Generated 

A  CirculateNotify  event  reports  a  call  to  change  the  stacking  order,  and  it  includes 
whether  the  final  position  is  on  the  top  or  on  the  bottom.  This  event  is  generated  by 

XCirculateSubwindows,  XCirculateSubwindowsDown,  or  XCirculate- 
SubwindowsUp.  See  also  the  CirculateRequest  and  Conf  igureNotify  events. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  CirculateNotify  may  be  used,  or  use  the  abbreviation 

Circ. 

Select  With 

This  event  is  selected  with  StructureNotifyMask  in  the  XSelectlnput  call,  for  the 
window  to  be  moved,  or  with  SubstructureNotifyMask,  for  the  parent  of  the  window  to 
be  moved. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XCirculateEvent  xcirculate; 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial, 

Bool  send_event; 

Display  *display; 

Window  event; 

Window  window; 

int  place; 
}  XCirculateEvent; 


/*  #  of  last  request  processed  by  server  */ 
/*  TRUE  if  this  came  from  SendEvent  request 
/*  display  the  event  was  read  from  */ 


/*  PlaceOnTop,  PlaceOnBottom  */ 


Event  Structure  Members 

event  The  window  receiving  the  event  If  the  event  was  selected  by  Structure 
NotifyMask,  event  will  be  the  same  as  window.  If  the  event  was  selected  by 
SubstructureNotifyMask,  event  will  be  the  parent  of  window. 

window      The  window  that  was  restacked. 

place  Either  PlaceOnTop  or  PlaceOnBottom.  Indicates  whether  the  window  was 
raised  to  the  top  or  bottom  of  the  stack. 
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— xcirculaterequest- 


CirculateRequest 


When  Generated 

A  CirculateRequest  event  reports  when  XCirculateSubwindows,  XCirculate- 
SubwindowsDown,  XCirculateSubwindowsUp,  or  XRestackWindows  is  called  to 
change  the  stacking  order  of  a  group  of  children. 

This  event  differs  from  CirculateNotif  y  in  that  it  delivers  the  parameters  of  the  request 
before  it  is  carried  out.  This  gives  the  client  that  selects  this  event  (usually  the  window  man 
ager)  the  opportunity  to  review  the  request  in  the  light  of  its  window  management  policy  before 
executing  the  circulate  request  itself  or  to  deny  the  request.  (CirculateNotify  indicates 
the  final  outcome  of  the  request.) 

Translation  Abbreviations 

In  translation  tables,  the  event  type  CirculateNotify  may  be  used,  or  use  the  abbreviation 

CircRec. 

Select  With 

This  event  is  selected  for  the  parent  window  with  SubstructureRedirectMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XCirculateRequest Event  xcirculaterequest; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial; 

Bool  send_event; 

Display  ^display; 

Window  parent; 

Window  window; 

int  place; 
}  XCirculateRequestEvent; 

Event  Structure  Members 


/*  #  of  last  request  processed  by  server  */ 
/*  TRUE  if  this  came  from  SendEvent  request 
/*  display  the  event  was  read  from  */ 


/*  PlaceOnTop,  PlaceOnBottom  */ 


parent      The  parent  of  the  window  that  was  restacked.  This  is  the  window  that  selected  the 
event 

window      The  window  being  restacked. 

place        PlaceOnTop  or  PlaceOnBottom.   Indicates  whether  the  window  was  to  be 
placed  on  top  or  on  the  bottom  of  the  stacking  order. 
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ClientMessage  \ 


•xclient — 


When  Generated 

A  ClientMessage  event  is  sent  as  a  result  of  a  call  to  XSendEvent  by  a  client  to  a  particu 
lar  window.  Any  type  of  event  can  be  sent  with  XSendEvent,  but  it  will  be  distinguished 
from  normal  events  by  the  send_event  member  being  set  to  TRUE.  If  your  program  wants  to 
be  able  to  treat  events  sent  with  XSendEvent  as  different  from  normal  events,  you  can  check 
the  send_event  member,  or  you  can  provide  a  translation  for  ClientMessage  events. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  ClientMessage  may  be  used,  or  use  the  abbreviation 

Message. 

The  type  of  ClientMessge  event  (the  message_type  field)  can  be  specified  as  a  detail  in 
the  translation  (see  PropertyNotif  y). 

Select  With 

There  is  no  event  mask  for  ClientMessage  events,  and  they  are  not  selected  with 
XSelect Input.  Instead  XSendEvent  directs  them  to  a  specific  window,  which  is  given  as 
a  window  ID:  the  PointerWindow  or  the  InputFocus. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XClientMessageEvent  xclient; 
}  XEvent; 

Event  Structure 

typedef  struct  {  ,.' 

int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 
Bool  send_event;      /*  TRUE  if  this  came  from  SendEvent  request  */ 
Display  *display;     /*  display  the  event  was  read  from  */ 
Window  window; 
Atom  message_type; 
int  format; 
union  { 

char  b[20] ; 

short  s [10]  ; 

long  1[5] ; 
}  data; 
}  XClientMessageEvent; 

Event  Structure  Members 

message_type 

An  atom  that  specifies  how  the  data  is  to  be  interpreted  by  the  receiving  client. 
The  X  server  places  no  interpretation  on  the  type  or  the  data,  but  it  must  be  a  list  of 
8-bit,  16-bit,  or  32-bit  quantities,  so  that  the  X  server  can  correctly  swap  bytes  as 
necessary.  The  data  always  consists  of  twenty  8-bit  values,  ten  16-bit  values,  or 
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Client  Message 


five  32-bit  values,  although  each  particular  message  might  not  make  use  of  all  of 
these  values. 

format      Specifies  the  format  of  the  property  specified  by  message_type.  This  will  be  on 
of  the  values  8, 16,  or  32. 
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X 


•xcolormap — 


When  Generated 

A  ColormapNotify  event  reports  when  the  colormap  attribute  of  a  window  changes  or 
when  the  colormap  specified  by  the  attribute  is  installed,  uninstalled,  or  freed.  This  event  is 
generated  by  XChangeWindowAttributes,  XFreeColormap,  XInstallColormap, 
and  XUninstallColormap. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  ColormapNotify  may  be  used,  or  use  the  abbreviation 

Clrmap. 

Select  With 

This  event  is  selected  with  ColormapChangeMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XColormapEvent  xcolormap; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial, 

Bool  send_event; 

Display  *display; 

Window  window; 

Colormap  colormap; 

Bool  new; 

int  state; 
}  XColormapEvent; 


/*  #  of  last  request  processed  by  server  */ 

/*  TRUE  if  this  came  from  SendEvent  request  * 

/*  display  the  event  was  read  from  */ 

/*  A  colormap  or  None  */ 

/*  Colormaplnstalled,  ColormapUninstalled  */ 


Event  Structure  Members 

window         The  window  whose  associated  colormap  or  attribute  changes. 

colormap  The  colormap  associated  with  the  window,  either  a  colormap  ID  or  the  constant 
None.  It  will  be  None  only  if  this  event  was  generated  due  to  an  XFree 
Colormap  call. 

new  TRUE  when  the  colormap  attribute  has  been  changed,  or  FALSE  when  the  color- 

map  is  installed  or  uninstalled. 

state  Either   Colormaplnstalled  or  ColormapUninstalled;   it  indicates 

whether  the  colormap  is  installed  or  uninstalled. 
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—xconfigure ^ 

When  Generated 

A  ConfigureNotify  event  announces  actual  changes  to  a  window's  configuration  (size, 
position,  border,  and  stacking  order).  See  also  the  CirculateRequest  event 

Translation  Abbreviations 

In  translation  tables,  the  event  type  ConfigureNotify  may  be  used,  or  use  the  abbreviation 

Configure. 

Select  With 

This  event  is  selected  for  a  single  window  by  specifying  the  window  ID  of  that  window  with 
StructureNotifyMask.  To  receive  this  event  for  all  children  of  a  window,  specify  the 
parent  window  ID  with  SubstructureNotifyMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XConf igureEvent  xconfigure; 
}  XEvent; 

Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 
Bool  send  event;      /*  TRUE  if  this  came  from  SendEvent  request  */ 
Display  *display;     /*  display  the  event  was  read  from  */ 
Window  event; 
Window  window; 
int  x,  y; 

int  width,  height; 
int  border_width; 
Window  above; 
Bool  override_redirect; 
}  XConf igureEvent; 

Event  Structure  Members 

event         The  window  that  selected  the  event  The  event  and  window  members  are  identi 
cal  if  the  event  was  selected  with  StructureNotifyMask. 

window      The  window  whose  configuration  was  changed. 

x ,    y  The  final  coordinates  of  the  reconfigured  window  relative  to  its  parent 

width,  height 

The  width  and  height  in  pixels  of  the  window  after  reconfiguration. 

border_width 

The  width  in  pixels  of  the  border  after  reconfiguration. 
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above  If  this  member  is  None,  then  the  window  is  on  the  bottom  of  the  stack  with  respect 
to  its  siblings.  Otherwise,  the  window  is  immediately  on  top  of  the  specified  sib 
ling  window. 

override_redirect 

The  override_redirect  attribute  of  the  reconfigured  window.  If  TRUE,  it 
indicates  that  the  client  wants  this  window  to  be  immune  to  interception  by  the 
window  manager  of  configuration  requests.  Window  managers  normally  should 
ignore  this  event  if  override_redirect  is  TRUE. 
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ConfigureRequest 


When  Generated 

A  ConfigureRequest  event  reports  when  another  client  attempts  to  change  a  window's 
size,  position,  border,  and/or  stacking  order. 

This  event  differs  from  Conf  igureNotify  in  that  it  delivers  the  parameters  of  the  request 
before  it  is  carried  out.  This  gives  the  client  that  selects  this  event  (usually  the  window  man 
ager)  the  opportunity  to  revise  the  requested  configuration  before  executing  the 
XConf  igureWindow  request  itself  or  to  deny  the  request.  (Conf  igureNotify  indicates 
the  final  outcome  of  the  request.) 

Translation  Abbreviations 

In  translation  tables,  the  event  type  ConfigureRequest  may  be  used,  or  use  the  abbrevia 
tion  Conf igureReq. 

Select  With 

This  event  is  selected  for  any  window  in  a  group  of  children  by  specifying  the  parent  window 
with  SubstructureRedirectMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XConf igureRequest Event  xconf igurerequest; 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial 

Bool  send_event; 

Display  *display; 

Window  parent; 

Window  window; 

int  x,  y; 

int  width,  height; 

int  border_width; 

Window  above; 

int  detail; 

unsigned  long  value_mask; 
}  XConf igureRequestEvent; 

Event  Structure  Members 

parent      The  window  that  selected  the  event.  This  is  the  parent  of  the  window  being  config 
ured. 

window      The  window  that  is  being  configured. 

x,    y          The  requested  position  for  the  upper-left  pixel  of  the  window's  border  relative  to 
the  origin  of  the  parent  window. 


#  of  last  request  processed  by  server  */ 
TRUE  if  this  came  from  SendEvent  request 
display  the  event  was  read  from  */ 


/*  Above,  Below,  Toplf,  Bottomlf,  Opposite  */ 
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ConfigureRequest  (continued)  xconfigurerequest 

width,  height 

The  requested  width  and  height  in  pixels  for  the  window. 

border_width 

The  requested  border  width  for  the  window. 

above  None,  Above,  Below,  Toplf ,  Bottomlf ,  or  Opposite.  Specifies  the  sibling 
window  on  top  of  which  the  specified  window  should  be  placed.  If  this  member 
has  the  constant  None,  then  the  specified  window  should  be  placed  on  the  bottom. 

Notes 

The  geometry  is  derived  from  the  XConf  igureWindow  request  that  triggered  the  event. 
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CreateNotify 


When  Generated 

A  CreateNotify  event  reports  when  a  window  is  created. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  CreateNotify  may  be  used,  or  use  the  abbreviation 

Create. 

Select  With 

This  event  is  selected  on  children  of  a  window  by  specifying  the  parent  window  ID  with 
SubstructureNotifyMask.     (Note    that    this    event    type    cannot    be    selected    by 

StructureNotifyMask). 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XCreateWindowEvent  xcreatewindow; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial; 

Bool  send_event; 

Display  *display; 

Window  parent; 

Window  window; 

int  x,  y; 

int  width,  height; 

int  border_width; 

Bool  override_redirect, 
}  XCreateWindowEvent; 


/*  #  of  last  request  processed  by  server  */ 
*  TRUE  if  this  came  from  SendEvent  request  */ 
/*  display  the  event  was  read  from  */ 

parent  of  the  window  */ 

window  ID  of  window  created  */ 

window  location  */ 

size  of  window  */ 

border  width  */ 

creation  should  be  overridden  V 


Event  Structure  Members 

pa  rent  The  ID  of  the  created  window's  parent 

window  The  ID  of  the  created  window. 

x ,    y  The  coordinates  of  the  created  window  relative  to  its  parent. 

width ,    height  The  width  and  height  in  pixels  of  the  created  window. 

border_width  The  width  in  pixels  of  the  border  of  the  created  window. 

override_redirect 

The  override_redirect  attribute  of  the  created  window.  If  TRUE,  it 
indicates  that  the  client  wants  this  window  to  be  immune  to  interception 
by  the  window  manager  of  configuration  requests.  Window  managers 
normally  should  ignore  this  event  if  override_redirect  is  TRUE. 
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CreateNOtify  (continued)  xcreatewindow 

Notes 

For  descriptions  of  these  members,  see  the  XCreateWindow  function  and  the  XSet- 
WindowAt tributes  structure. 
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DestroyNotify 


When  Generated 

A  DestroyNotify  event  reports  that  a  window  has  been  destroyed. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  DestroyNotify  may  be  used,  or  use  the  abbreviation 

Destroy. 

Select  With 

To  receive  this  event  type  on  children  of  a  window,  specify  the  parent  window  ID  and  pass 
SubstructureNotifyMask  as  part  of  the  event_mask  argument  to  XSelectlnput. 
This  event  type  cannot  be  selected  with  StructureNotif  yMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XDestroyWindowEvent  xdes troy window; 
}  XEvent; 


Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial;  /' 
Bool  send_event;      /' 
Display  *display;     /' 
Window  event; 
Window  window; 

}  XDestroyWindowEvent; 


#  of  last  request  processed  by  server  */ 
TRUE  if  this  came  from  SendEvent  request 
display  the  event  was  read  from  */ 


Event  Structure  Members 

event         The  window  that  selected  the  event. 

window      The  window  that  was  destroyed. 
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EnterNotify,  LeaveNotify 


•xcrossing  — 


When  Generated 

EnterNotify  and  LeaveNotify  events  occur  when  the  pointer  enters  or  leaves  a  window. 

When  the  pointer  crosses  a  window  border,  a  LeaveNotify  event  occurs  in  the  window 
being  left  and  an  EnterNotify  event  occurs  in  the  window  being  entered.  Whether  or  not 
each  event  is  queued  for  any  application  depends  on  whether  any  application  selected  the  right 
event  on  the  window  in  which  it  occurred. 

In  addition,  EnterNotify  and  LeaveNotify  events  are  delivered  to  windows  that  are  vir 
tually  crossed.  These  are  windows  that  are  between  the  origin  and  destination  windows  in  the 
hierarchy  but  not  necessarily  on  the  screen.  Further  explanation  of  virtual  crossing  is  provided 
two  pages  following. 

Translation  Abbreviations 

In  translation  tables,  the  event  types  EnterNotify  and  LeaveNotify  may  be  used,  or  use 
one  of  the  abbreviations  shown  in  the  following  table. 


Abbreviation 


Enter 

EnterWindow 
Leave 
LeaveWindow 


Description 


Pointer  entered  window 
Pointer  entered  window 
Pointer  left  window 
Pointer  left  window 


Normally,  enter  and  leave  events  that  occur  because  of  grabs  are  treated  just  like  normal  enter 
and  leave  events.  To  handle  them  differently,  you  can  use  any  of  the  abbreviations  above 
together  with  a  detail.  For  example,  in  the  translation: 

<Enter>Grab:  grabbed ()\n\ 
<Leave>Ungrab:  ungrabbed() 

The  specified  actions  will  be  invoked  only  when  the  pointer  enters  or  leaves  the  widget  because 
of  a  grab  or  ungrab.  The  default  is  equivalent  to  the  following  translation: 

<Enter>Normal :    allEventsO 

The  Core  widget  field  compress_enterleave  controls  whether  pairs  of  EnterNotify 
and  LeaveNotify  events  with  no  intervening  events  are  ignored.  For  more  information,  see 
Chapter  8,  More  Input  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Man 
ual. 

Select  With 

Each  of  these  events  can  be  selected  separately  with  XEnterWindowMask  and  XLeave- 
WindowMask. 
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XEvent  Structure  Name 

typedef  union  _XEvent  { 

XCrossingEvent  xcrossing; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type;  /' 
unsigned  long  serial;  /' 

Bool  send_event;  /' 

Display  *display;  /' 

Window  window;  /' 

Window  root;  /' 

Window  subwindow;  /' 

Time  time;  /' 

int  x,  y;  /' 

int  x_root,  y_root;  /' 

int  mode;  /' 

int  detail;  /' 


of  event  */ 

#  of  last  request  processed  by  server  */ 

TRUE  if  this  came  from  SendEvent  request  */ 

display  the  event  was  read  from  */ 

event  window  it  is  reported  relative  to  */ 

root  window  that  the  event  occurred  on  */ 

child  window  */ 

milliseconds  */ 

pointer  x,  y  coordinates  in  receiving  window  */ 

coordinates  relative  to  root  */ 

NotifyNormal,  NotifyGrab,  NotifyUngrab  */ 

NotifyAncestor,  NotifyVirtual,  Notifylnferior, 

NotifyNonLinear,  NotifyNonLinearVirtual  */ 

same  screen  flag  */ 

Boolean  focus  */ 

key  or  button  mask  */ 


Bool  same_screen;     A 

Bool  focus;  /: 

unsigned  int  state;   /: 
}  XCrossingEvent; 

typedef  XCrossingEvent  XEnterWindowEvent; 
typedef  XCrossingEvent  XLeaveWindowEvent; 

Event  Structure  Members 

subwindow  In  a  LeaveNotify  event,  if  the  pointer  began  in  a  child  of  the  receiving  win 
dow  then  the  child  member  is  set  to  the  window  ID  of  the  child.  Otherwise,  it 
is  set  to  None.  For  an  EnterNotify  event,  if  the  pointer  ends  up  in  a  child  of 
the  receiving  window  then  the  child  member  is  set  to  the  window  ID  of  the 
child.  Otherwise,  it  is  set  to  None. 

time  The  server  time  when  the  crossing  event  occurred,  in  milliseconds.    Time  is 

declared  as  unsigned    long,  so  it  wraps  around  when  it  reaches  the  maxi 
mum  value  of  a  32  bit  number  (every  49.7  days). 

x ,    y  The  point  of  entry  or  exit  of  the  pointer  relative  to  the  event  window. 

x_root,  y_root 

The  point  of  entry  or  exit  of  the  pointer  relative  to  the  root  window. 

mode  Normal  crossing  events  or  those  caused  by  pointer  warps  have  mode  Notify 

Normal;  events  caused  by  a  grab  have  mode  NotifyGrab;  and  events  caused 
by  a  released  grab  have  mode  NotifyUngrab. 
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detail  The  value  of  the  detail  member  depends  on  the  hierarchical  relationship 
between  the  origin  and  destination  windows  and  the  direction  of  pointer  transfer. 
Determining  which  windows  receive  events  and  with  which  detail  members 
is  quite  complicated.  This  topic  is  described  in  the  next  section. 

same_screen 

Indicates  whether  the  pointer  is  currently  on  the  same  screen  as  this  window. 
This  is  always  TRUE  unless  the  pointer  was  actively  grabbed  before  the  auto 
matic  grab  could  take  place. 

focus  If  the  receiving  window  is  the  focus  window  or  a  descendant  of  the  focus  win 

dow,  the  focus  member  is  TRUE;  otherwise  it  is  FALSE. 

state  The  state  of  all  the  buttons  and  modifier  keys  just  before  the  event,  represented 

by  a  mask  of  the  button  and  modifier  key  symbols:  ButtonlMask, 
Button2Mask,  ButtonSMask,  Button4Mask,  ButtonSMask,  Shift- 
Mask,  ControlMask,  LockMask,  ModlMask,  Mod2Mask,  ModSMask, 
Mod4Mask,  and  ModSMask. 

Virtual  Crossing  and  the  detail  Member 

Virtual  crossing  occurs  when  the  pointer  moves  between  two  windows  that  do  not  have  a 
parent-child  relationship.  Windows  between  the  origin  and  destination  windows  in  the  hierar 
chy  receive  EnterNotify  and  LeaveNotify  events.  The  detail  member  of  each  of 
these  events  depends  on  the  hierarchical  relationship  of  the  origin  and  destination  windows  and 
the  direction  of  pointer  transfer. 

Virtual  crossing  is  an  advanced  topic  that  you  shouldn't  spend  time  figuring  out  unless  you 
have  an  important  reason  to  use  it.  I  have  never  seen  an  application  that  uses  this  feature,  and  I 
know  of  no  reason  for  its  extreme  complexity.  With  that  word  of  warning,  proceed. 

Let's  say  the  pointer  has  moved  from  one  window,  the  origin,  to  another,  the  destination.  First 
we'll  specify  what  types  of  events  each  window  gets,  and  then  the  detail  member  of  each  of 
those  events. 

The  window  of  origin  receives  a  LeaveNotify  event  and  the  destination  window  receives  an 
EnterNotify  event,  if  they  have  requested  this  type  of  event.  If  one  is  an  inferior  of  the 
other,  the  detail  member  of  the  event  received  by  the  inferior  is  NotifyAncestor  and  the 
detail  of  the  event  received  by  the  superior  is  Notif  ylnf  erior.  If  the  crossing  is  between 
parent  and  child,  these  are  the  only  events  generated. 

However,  if  the  origin  and  destination  windows  are  not  parent  and  child,  other  windows  are  vir 
tually  crossed  and  also  receive  events.  If  neither  window  is  an  ancestor  of  the  other,  ancestors 
of  each  window  up  to  but  not  including  the  least  common  ancestor  receive  LeaveNotify 
events  if  they  are  in  the  same  branch  of  the  hierarchy  as  the  origin  and  EnterNotify  events 
if  they  are  in  the  same  branch  as  the  destination.  These  events  can  be  used  to  track  the  motion 
of  the  pointer  through  the  hierarchy. 

•     In  the  case  of  a  crossing  between  a  parent  and  a  child  of  a  child,  the  middle  child  receives  a 
LeaveNotify  with  detail  NotifyVirtual. 
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•  In  the  case  of  a  crossing  between  a  child  and  the  parent  of  its  parent,  the  middle  child 
receives  an  EnterNotify  with  detail  NotifyVirtual. 

•  In  a  crossing  between  windows  whose  least  common  ancestor  is  two  or  more  windows 
away,  both  the  origin  and  destination  windows  receive  events  with  detail  Not  if  y- 
Nonlinear.  The  windows  between  the  origin  and  the  destination  in  the  hierarchy,  up  to 
but  not  including  their  least  common  ancestor,  receive  events  with  detail  Not  if  y- 
NonlinearVirtual.  The  least  common  ancestor  is  the  lowest  window  from  which  both 
are  descendants. 

•  If  the  origin  and  destination  windows  are  on  separate  screens,  the  events  and  details  gen 
erated  are  the  same  as  for  two  windows  not  parent  and  child,  except  that  the  root  windows 
of  the  two  screens  are  considered  the  least  common  ancestor.   Both  root  windows  also 
receive  events. 

Table  C-2  shows  the  event  types  generated  by  a  pointer  crossing  from  window  A  to  window  B 
when  window  C  is  the  least  common  ancestor  of  A  and  5. 

Table  C-2.  Border  Crossing  Events  and  Window  Relationship 


LeaveNotify 


Origin  window  (A) 

Windows  between  A  and  B  exclusive  if 
A  is  inferior 

Windows  between  A  and  C  exclusive 

Root  window  on  screen  of  origin  if  dif 
ferent  from  screen  of  destination 


EnterNotify 


Destination  window  (B) 

Windows  between  A  and  B  exclusive  if 
B  is  inferior 

Windows  between  B  and  C  exclusive 

Root  window  on  screen  of  destination  if 
different  from  screen  of  origin 


Table  C-3  lists  the  detail  members  in  events  generated  by  a  pointer  crossing  from  window  A 
to  window  B. 

Table  C-3.  Event  detail  Member  and  Window  Relationship 


detail  Flag 


NotifyAncestor 
Notify Inferior 
NotifyVirtual 

Not ifyNon linear 


Window  Delivered  To 


Origin  or  destination  when  either  is  descendant 
Origin  or  destination  when  either  is  ancestor. 

Windows  between  A  and  B  exclusive  if  either  is 
descendant. 

Origin  and  destination  when  A  and  B  are  two  or  more 
windows  distant  from  least  common  ancestor  C, 
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EnterNotify,  LeaveNotify 


(continued) 


xcrossing 


detail  Rag 


Window  Delivered  To 


NotifyNonlinearVirtual 


Windows  between  A  and  C  exclusive  and  between  B 
and  C  exclusive  when  A  and  B  have  least  common 
ancestor  C.  Also  on  both  root  windows  if  A  and  B 
are  on  different  screens. 


For  example,  Figure  C-l  shows  the  events  that  are  generated  by  a  movement  from  a  window 
(window  A)  to  a  child  (window  57)  of  a  sibling  (window  /?).  This  would  generate  three  events: 
a  LeaveNotify  with  detail  Notif  yNonlinear  for  the  window  A,  an  EnterNotify  with 
detail  NotifyNonlinearVirtual  for  its  sibling  window  B,  and  an  EnterNotify  with 
detail  Notif  yNonlinear  for  the  child  (window  Bl). 


Root  Window 

(no  event) 


r   \. 


LeaveNotify  event  with  detail 

NotifyNonlinear 


A1 


no  event 


EnterNotify  event  with  dfetail 

NotifyNonlinearVirtual 


B1 

EnterNotify  event  with  detail 

Not if yNonlinear 


Figure  C-1.  Events  generated  by  a  move  between  windows 

EnterNotify  and  LeaveNotify  events  are  also  generated  when  the  pointer  is  grabbed,  if 
the  pointer  was  not  already  inside  the  grabbing  window.  In  this  case,  the  grabbing  window 
receives  an  EnterNotify  and  the  window  containing  the  pointer  receives  a  LeaveNotify 
event,  both  with  mode  NotifyUngrab.  The  pointer  position  in  both  events  is  the  position 
before  the  grab.  The  result  when  the  grab  is  released  is  exactly  the  same  except  that  the  two 
windows  receive  EnterNotify  instead  of  LeaveNotify  and  vice  versa. 
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xcrossing 


(continued) 


EnterNotify,  LeaveNotify 


Figure  C-2  demonstrates  the  events  and  details  caused  by  various  pointer  transitions,  indicated 
by  heavy  arrows. 


EnterNotify, 

Inferior 


LeaveNotify, 
Virtual 


LeaveNotify, 
Ancestor 


EnterNotify, 

Inferior 


LeaveNotify, 

Virtual 


LeaveNotify, 
Ancestor 


m 

LeaveNotify,     ROOt  I     Root  I   LeaveNotify, 
NonLinearVirtual    (jf  ^  I      Of  8   1  NonLinearVirtual 

LeaveNotify,                     LeaveNotify, 
NonLinearVirtual  1              NonLinearVirtual 

LeaveNotify,     .           ft    1  EnterNotify, 
NonLinear          |^    **   1    NonLinear 

LeaveNotify,       .    ^^-     n       EnterNotify, 
NonLinear            |^    "         NonLinear 

Figure  C-2.  Border  crossing  events  and  detail  member  for  pointer  movement  from  window  A  to 
window  B,  for  various  window  relationships 
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Expose 


X 


•xexpose — 


When  Generated 

An  Expose  event  is  generated  when  a  window  becomes  visible  or  a  previously  invisible  part 
of  a  window  becomes  visible.  Only  inputOutput  windows  generate  or  need  to  respond  to 
Expose  events;  inputOnly  windows  never  generate  or  need  to  respond  to  them.  The 
Expose  event  provides  the  position  and  size  of  the  exposed  area  within  the  window  and  a 
rough  count  of  the  number  of  remaining  exposure  events  for  the  current  window. 

Only  when  an  application  adds  drawing  capability  to  a  widget  from  the  application  will  a  trans 
lation  or  event  handler  for  Expose  events  be  necessarily.  Xt  automatically  calls  the  expose 
method  of  each  widget  in  response  to  these  events. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  Expose  is  the  only  valid  string;  there  are  no  abbreviations. 

The  Core  widget  field  compress_exposures  controls  whether  contiguous  Expose  events 
are  coalesced  before  calling  a  widget's  expose  method.  For  more  information,  see  Chapter 
8,  More  Input  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 

Select  With 

This  event  is  selected  with  ExposureMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XExposeEvent  xexpose; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial, 

Bool  send_event; 

Display  *display; 

Window  window; 

int  x,  y; 

int  width,  height; 

int  count; 
}  XExposeEvent; 


/*  #  of  last  request  processed  by  server  */ 
/*  TRUE  if  this  came  from  SendEvent  request 
/*  display  the  event  was  read  from  */ 


/*  if  nonzero,  at  least  this  many  more  */ 


Event  Structure  Members 

x,    y  The  coordinates  of  the  upper-left  corner  of  the  exposed  region  relative  to 

the  origin  of  the  window. 

widt  h ,    he i ght    The  width  and  height  in  pixels  of  the  exposed  region. 

count  The  approximate  number  of  remaining  contiguous  Expose  events  that 

were  generated  as  a  result  of  a  single  function  call. 
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xexpose  (continued)  Expose 

Notes 

A  single  action  such  as  a  window  movement  or  a  function  call  can  generate  several  exposure 
events  on  one  window  or  on  several  windows.  The  server  guarantees  that  all  exposure  events 
generated  from  a  single  action  will  be  sent  contiguously,  so  that  they  can  all  be  handled  before 
moving  on  to  other  event  types.  This  allows  an  application  to  keep  track  of  the  rectangles 
specified  in  contiguous  Expose  events,  set  the  clip_mask  in  a  GC  to  the  areas  specified  in 
the  rectangle  using  XSetRegion  or  XSetClipRectangles,  and  then  finally  redraw  the 
window  clipped  with  the  GC  in  a  single  operation  after  all  the  Expose  events  have  arrived. 
The  last  event  to  arrive  is  indicated  by  a  count  of  0.  In  Release  2,  XUnionRectwith- 
Region  can  be  used  to  add  the  rectangle  in  Expose  events  to  a  region  before  calling  XSet 
Region. 

If  your  application  is  able  to  redraw  partial  windows,  you  can  also  read  each  exposure  event  in 
turn  and  redraw  each  area. 
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Focusln,  FocusOut  X 


•xfocus — 


When  Generated 

Focusln  and  FocusOut  events  occur  when  the  keyboard  focus  window  changes,  as  a  result 
of  an  XSetlnputFocus  call.  They  are  much  like  EnterNotify  and  LeaveNotify 
events  except  that  they  track  the  focus  rather  than  the  pointer. 

When  a  focus  change  occurs,  a  FocusOut  event  is  delivered  to  the  old  focus  window  and  a 
Focusln  event  to  the  window  which  receives  the  focus.  In  addition,  windows  in  between 
these  two  windows  in  the  window  hierarchy  are  virtually  crossed  and  receive  focus  change 
events,  as  described  below.  Some  or  all  of  the  windows  between  the  window  containing  the 
pointer  at  the  time  of  the  focus  change  and  the  root  window  also  receive  focus  change  events, 
as  described  below. 

Translation  Abbreviations 

In  translation  tables,  the  event  types  Focusln  and  FocusOut  may  be  used;  there  are  no 
abbreviations. 

By  default,  translations  for  focus  change  events  detect  focus  changes  due  to  grabs  and  xtSet- 
KeyboardFocus  or  XSetlnputFocus  calls.  To  distinguish  these  different  types  of  focus 
change  events,  you  can  specify  a  detail  in  the  translation.  For  example,  to  be  notified  only  of 
focus  changes  resulting  from  grabs,  you  can  use  the  translation: 

<FocusIn>Grab:    gotFocusO 

For  other  types  of  focus  events,  you  can  use  the  details  Ungrab,  WhileGrabbed,  and  Nor 
mal. 

Select  With 

Focusln  and  FocusOut  events  are  selected  with  FocusChangeMaskv  They  cannot  be 
selected  separately. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XFocusChangeEvent  xfocus; 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type;  /*  Focusln  or  FocusOut  */ 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 
Bool  send_event;      /*  TRUE  if  this  came  from  SendEvent  request  */ 
Display  *display;     /*  display  the  event  was  read  from  */ 
Window  window;        /*  window  of  event  */ 

int  mode;  /*  NotifyNormal,  NotifyGrab,  NotifyUngrab, 

*  NotifyWhileGrabbed  */ 
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xfocus  (continued)  FOCUSln,   FOGUSOut 

int   detail;  /*  NotifyAncestor,    NotifyVirtual,    Notify- 

*  Inferior,  NotifyNonLinear,  NotifyNonLinear- 

*  Virtual,  NotifyPointer,  NotifyPointerRoot, 

*  NotifyDetailNone  */ 
}  XFocusChangeEvent; 

typedef  XFocusChangeEvent  XFocusInEvent; 
typedef  XFocusChangeEvent  XFocusOutEvent; 

Event  Structure  Members 

mode  For  events  generated  when  the  keyboard  is  not  grabbed,  mode  is  Not  if  y- 
Normal;  when  the  focus  change  occurs  while  the  keyboard  is  grabbed,  mode  is 
NotifyWhileGrabbed;  when  the  focus  change  results  from  a  grab,  mode  is 
NotifyGrab;  and  when  the  focus  change  results  from  an  ungrab,  mode  is 
NotifyUngrab. 

detail  The  detail  member  identifies  the  relationship  between  the  window  that  receives 
the  event  and  the  origin  and  destination  windows.  It  will  be  described  in  detail 
after  the  description  of  which  windows  get  what  types  of  events. 

Notes 

The  keyboard  focus  is  a  window  that  has  been  designated  as  the  one  to  receive  all  keyboard 
input  irrespective  of  the  pointer  position.  Only  the  keyboard  focus  window  and  its  descendants 
receive  keyboard  events.  By  default,  the  focus  window  is  the  root  window.  Since  all  windows 
are  descendants  of  the  root,  the  pointer  controls  the  window  that  receives  input. 

Most  window  managers  allow  the  user  to  set  a  focus  window,  to  avoid  the  problem  where  the 
pointer  sometimes  gets  bumped  into  the  wrong  window  and  your  typing  doesn't  go  to  the 
intended  window.  If  the  pointer  is  pointing  at  the  root  window,  all  typing  is  usually  lost  since 
there  is  no  application  for  this  input  to  propagate  to.  Some  applications  may  set  the  keyboard 
focus  so  that  they  can  get  all  keyboard  input  for  a  given  period  of  time,  but  this  practice  is  not 
encouraged. 

Focus  events  are  used  when  an  application  wants  to  act  differently  when  the  keyboard  focus  is 
set  to  another  window  or  to  itself.  FocusChangeMask  is  used  to  select  Focusln  and 
FocusOut  events. 

When  a  focus  change  occurs,  A  FocusOut  event  is  delivered  to  the  old  focus  window  and  a 
Focusln  event  is  delivered  to  the  window  which  receives  the  focus.  Windows  in  between  in 
the  hierarchy  are  virtually  crossed  and  receive  one  focus  change  event  each  depending  on  the 
relationship  and  direction  of  transfer  between  the  origin  and  destination  windows.  Some  or  all 
of  the  windows  between  the  window  containing  the  pointer  at  the  time  of  the  focus  change  and 
that  window's  root  window  can  also  receive  focus  change  events.  By  checking  the  detail 
member  of  Focusln  and  FocusOut  events,  an  application  can  tell  which  of  its  windows  can 
receive  input. 

The  detail  member  gives  clues  about  the  relationship  of  the  event  receiving  window  to  the 
origin  and  destination  of  the  focus.  The  detail  member  of  FocusOut  and  Focusln  events 
is  analogous  to  the  detail  member  of  LeaveNotif  y  and  EnterNotif  y  events,  but  with 
even  more  permutations  to  make  life  complicated. 
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Focusln,  FocusOut 


(continued) 


xfocus 


Virtual  Focus  Crossing  and  the  detail  Member 

We  will  now  embark  on  specifying  the  types  of  events  sent  to  each  window  and  the  detail 
member  in  each  event,  depending  on  the  relative  position  in  the  hierarchy  of  the  origin  window 
(old  focus),  destination  window  (new  focus),  and  the  pointer  window  (window  containing 
pointer  at  time  of  focus  change).  Don't  even  try  to  figure  this  out  unless  you  have  to. 

Table  C-4  shows  the  event  types  generated  by  a  focus  transition  from  window  A  to  window  B 
when  window  C  is  the  least  common  ancestor  of  A  and  B,  and  P  is  the  window  containing  the 
pointer.  This  table  includes  most  of  the  events  generated,  but  not  all  of  them.  It  is  quite  pos 
sible  for  a  single  window  to  receive  more  than  one  focus  change  event  from  a  single  focus 
change. 

Table  C-4.  Focusln  and  FocusOut  Events  and  Window  Relationship 


FocusOut 


Origin  window  (A) 

Windows  between  A  and  B  exclusive  if 
A  is  inferior 

Windows  between  A  and  C  exclusive 

Root  window  on  screen  of  origin  if  dif 
ferent  from  screen  of  destination 

Pointer  window  up  to  but  not  including 
origin  window  if  pointer  window  is 
descendant  of  origin 

Pointer  window  up  to  and  including 
pointer  window's  root  if  transfer  was 
from  PointerRoot 


Focusln 


Destination  window  (B) 

Windows  between  A  and  B  exclusive  if 
B  is  inferior 

Windows  between  B  and  C  exclusive 

Root  window  on  screen  of  destination  if 
different  from  screen  of  origin 

Pointer  window  up  to  but  not  including 
destination  window  if  pointer  window  is 
descendant  of  destination 

Pointer  window  up  to  and  including 
pointer  window's  root  if  transfer  was  to 

PointerRoot 
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xfocus 


(continued) 


Focusln,  FocusOut 


Table  C-5  lists  the  detail  members  in  events  generated  by  a  focus  transition  from  window  A 
to  window  B,  with  P  being  the  window  containing  the  pointer. 

Table  C-5.  Event  detail  Member  and  Window  Relationship 


detail  Rag 


NotifyAncestor 
Notifylnferior 
NotifyVirtual 

Not ifyNon linear 
NotifyNonlinearVirtual 


NotifyPointer 
NotifyPointerRoot 

NotifyDetailNone 


Window  Delivered  To 


Origin  or  destination  when  either  is  descendant. 
Origin  or  destination  when  either  is  ancestor. 

Windows  between  A  and  B  exclusive  if  either  is 
descendant. 

Origin  and  destination  when  A  and  B  are  two  or  more 
windows  distant  from  least  common  ancestor  C. 

Windows  between  A  and  C  exclusive  and  between  B 
and  C  exclusive  when  A  and  B  have  least  common 
ancestor  C.  Also  on  both  root  windows  if  A  and  B 
are  on  different  screens. 

Window  P  and  windows  up  to  but  not  including  the 
origin  or  destination  windows. 

Window  P  and  all  windows  up  to  its  root,  and  all 
other  roots,  when  focus  is  set  to  or  from  Pointer- 
Root. 

All  roots,  when  focus  is  set  to  or  from  None. 


The  following  two  pages  show  all  the  possible  combinations  of  focus  transitions  and  of  origin, 
destination,  and  pointer  windows  and  shows  the  types  of  events  that  are  generated  and  their 
detail  member.  Solid  lines  indicate  branches  of  the  hierarchy.  Dotted  arrows  indicate  the 
direction  of  transition  of  the  focus.  At  each  end  of  this  arrow  are  the  origin  and  destination 
windows,  windows  A  to  B.  Arrows  ending  in  a  bar  indicate  that  the  event  type  and  detail 
described  are  delivered  to  all  windows  up  to  the  bar. 

In  any  branch,  there  may  be  windows  that  are  not  shown.  Windows  in  a  single  branch  between 
two  boxes  shown  will  get  the  event  types  and  details  shown  beside  the  branch. 
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Focusln,  FocusOut 


(continued) 


xfocus 


If  window  P  is  between  A  and  B, 
w  ndows  from  P  up  to  but  not 
including  B  get  Focusin  with 

detail  Motif  ylnterior 

EnterNotify,                n 
Inferior 

EnterNotify,             B 
Inferior 

>  , 
LeaveNotify,                    ^  
Virtual 
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LeaveNotify,                      * 

Virtual 

LeaveNotify,                « 
Ancestor 
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Focusln  With  Detail  PointerRoot 
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Root  Window  1 

sin, 
erRoot         FOCUS; 
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FocusOut,                                                                          Focusln, 
NonLinearVirtual                                                      NonLinearVirtual 
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NonLinear 

n                       Focusln, 
NonLinear 

».                      FocusOut, 
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T 
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Pointer 
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_i 

Roots  of  other  Screens: 
Focusln  Wth  Detail  None 
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Figure  C-3.  Focusln  and  FocusOut  event  schematics 
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(continued) 


Focusln,  FocusOut 


Roots  of  other  Screens: 
FocusOut  with  Detail  PointerRoot 

Roots  of  other  Screens: 

FocusOut  With  Detail  None 

Root  Window 

Focusln                                                                     Focusln, 
None    '                FOCUS!                             NonLinearVirtual 

PointerRoot 

ROOt  WindOW                      Focusln, 

FOCUS:  None 

I     JU     1 

t                            1 

«                                  Focusln, 
*                                NonLinear 

*        1                      NonLinear 

T 

T 

Focusln, 
Pointer 

n                                  Focusln, 

Pointer 

^^^    Focus  change  from  PointerRoot  to  None 
All  Root  W  ndows: 

FocusOut  With  Detail  PointerRoot 

••••^    Focus  change  from  PointerRoot  to  None 
All  Root  Windows: 

FocusOut  With  Detail  None 

FocusOut,              Pointer's 

PointerRoot               ftOOtWtlldOW 

Focusin,               Pointer's 

PointerRoot               ROOtWfRdOW 

~    in 

m 

Figure  C-3.  Focusln  and  FocusOut  event  schematics  (continued) 

Focusln  and  FocusOut  events  are  also  generated  when  the  keyboard  is  grabbed,  if  the  focus 
was  not  already  assigned  to  the  grabbing  window.  In  this  case,  all  windows  receive  events  as  if 
the  focus  was  set  from  the  current  focus  to  the  grab  window.  When  the  grab  is  released,  the 
events  generated  are  just  as  if  the  focus  was  set  back. 
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GraphicsExpose,  NoExpose          , xnoexpose- 

When  Generated 

GraphicsExpose  events  indicate  that  the  source  area  for  a  XCopyArea  or  XCopyPlane 
request  was  not  available  because  it  was  outside  the  source  window  or  obscured  by  a  window. 
NoExpose  events  indicate  that  the  source  region  was  completely  available. 

Neither  of  these  events  are  used  in  Xt's  automatic  processing  of  Expose  events.  If  a  widget 
needs  to  use  them,  it  must  provide  a  translation  or  event  handler  for  them  and  then  call  its 
expose  method  directly. 

Translation  Abbreviations 

In  translation  tables,  the  event  types  GraphicsExpose  and  NoExpose  may  be  used,  or  use 
the  abbreviations  GrExp  or  NoExp. 

Select  With 

These  events  are  not  selected  with  XSelect  Input  but  are  sent  if  the  GC  in  the  XCopyArea 
or  XCopyPlane  request  had  its  graphics_exposures  flag  set  to  TRUE.  If  graph- 
ics_exposures  is  TRUE  in  the  GC  used  for  the  copy,  either  one  NoExpose  event  or  one  or 
more  GraphicsExpose  events  will  be  generated  for  every  XCopyArea  or  XCopyPlane 
call  made. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XNoExposeEvent  xnoexpose; 
XGraphicsExposeEvent  xgraphicsexpose; 

}  XEvent; 

Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 
Bool  send_event;      /*  TRUE  if  this  came  from  SendEvent  request  */ 
Display  *display;     /*  display  the  event  was  read  from  */ 
Drawable  drawable; 
int  x,  y; 

int  width,  height; 

int  count;  /*  if  nonzero,  at  least  this  many  more  */ 

int  major_code;       /*  core  is  CopyArea  or  CopyPlane  */ 
int  minor_code;       /*  not  defined  in  the  core  */ 

}  XGraphicsExposeEvent; 

typedef  struct  { 
int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 
Bool  send_event;      /*  TRUE  if  this  came  from  SendEvent  request  */ 
Display  ^display;     /*  display  the  event  was  read  from  */ 
Drawable  drawable; 
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(continued) 


GraphicsExpose,  NoExpose 


int  major_code; 
int  minor_code; 
}  XNoExposeEvent ; 


/*  core  is  CopyArea  or  CopyPlane  */ 
/*  not  defined  in  the  core  */ 


Event  Structure  Members 

drawable  A  window  or  an  off-screen  pixmap.  This  specifies  the  destination  of  the 

graphics  request  that  generated  the  event 

x,    y  The  coordinates  of  the  upper-left  corner  of  the  exposed  region  relative  to 

the  origin  of  the  window. 

width ,    height    The  width  and  height  in  pixels  of  the  exposed  region. 

count  The  approximate  number  of  remaining  contiguous  GraphicsExpose 

events  that  were  generated  as  a  result  of  the  XCopyArea  or  XCopy- 
Plane  call. 

ma  j  or_code          The  graphics  request  used.  This  may  be  one  of  the  symbols  CopyArea  or 
CopyPlane,  or  a  symbol  defined  by  a  loaded  extension. 

minor  code          Zero  unless  the  request  is  part  of  an  extension. 


Notes 


Expose  events  and  GraphicsExpose  events  both  indicate  the  region  of  a  window  that  was 
actually  exposed  (x,  y,  width,  and  height).  Therefore  they  can  often  be  handled  similarly. 
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GravityNotify 


X 


xgravrty — 


V/hen  Generated 

A  GravityNotify  event  reports  when  a  window  is  moved  because  of  a  change  in  the  size  of 
its  parent  This  happens  when  the  win_gravity  attribute  of  the  child  window  is  something 
Other  than  S^ai-cl-ravi-.y  or  Vr.r.ep^ravity. 


Translation  Abbreviations 

In  translation  tables,  the  event  type  GravityNotify  may  be  used,  or  use  the  abbreviation 
Ira  v 


Select  With 
This  ever 
'  ~  rue" 
siblings,! 


lected  for  a  single  window  by  specifying  the  window  ID  of  that  window  with 
iifyMas/:.  To  receive  notification  of  movement  doe  to  gravil)  for  a  group  oi 

the  parent  window  ID  with  SubstructureNotif  yMask. 


XEverrt  Structure  Name 

_X£vent  { 

XGravityEvent  xgravity; 


Event  Structure 


.-..-.- 


serial;  /*  I  of  last  request  processed  by  server  */ 

/'  T?-;E  if  this  came  from  SendEvent  request  */ 
iy;     /»  display  the  event  was  read  frorf  */ 


-•-.-,    .       '    ,-..-'-.; 

Event  Structure  Members 

•-  •:  -'.-  -.  i        The  window  that  selected  the  event 

window      The  window  that  was  moved 


/.,     y 


The  new  coordinates  of  the  window  relative  to  its  parent 
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_rttymap / KeymapNotify 

When  Generated 

A  KeymapNot i  f y  event  reports  the  state  of  the  keyboard  md  occurs  when  the  pointer  or  ^ . 
hoard  focus  enters  a  window.     KeynvapNotify  events  are  reported  immediately  after 
Enter-Notify  or  Focusln  events.  This  is  a  way  for  die  application  10  read  the  keyboard 
state  as  the  application  is  "woken  up,"  since  the  two  triggering  events  usually  indicate  thai  the 
apyll.aiiu«  is  about  to  receive  user  input. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  KeymapNotify  may  be  used,  or  use  the  abbreviation 

Keying . 

Select  With 

This  event  is  selected  with  KeymapStateMask, 

XEvent  Structure  Name 

it    { 

XKe-. 

^  : 

Event  Structure 

it  { 
ff*S 

/*  *  c:  .-•^:  -.:-.-.. est  pro«-;-<>          er  */ 
/*  ".         .  s  came  from  Se  -.  - 

/*  display  the  event  was  read  fror  * 
.^.ow  wir-- 
char  key_\ ! 

\   c   .-,-:_. 

Event  Structure  Members 

wir..-  Reports  ihe  window  which  was  reported  in  the  window  member  of  the 

preceeding  EnterNot  ify  or  Focusln  event 

key_vector         A  bil  vector  or  mask,  each  bit  representing  one  physical  key.  with  a  total  of 
v  >  bits.  For  a  given  key,  its  keycode  is  its  position  in  the  keyboard  vector, 
You  CM  also  get  this  bit  vector  by  calling  XQue  ry Key-map. 

Notes 

The  serial  member  of  KeymapNotify  does  no*  contain  the  serial  number  of  the  mosi 
roccm  Protocol  Request  processed,  because  this  event  always  follows  immediately  after 
Focusln  or  EnterNotify  events  in  which  the  serial  member  is  valid. 


KeyPress,  KeyRelease 


X 


•xkey — 


When  Generated 

KeyPress  and  KeyRelease  events  are  generated  for  all  keys,  even  those  mapped  to  modi 
fier  keys  such  as  Shift  or  Control. 

Translation  Abbreviations 

In  translation  tables,  the  event  types  KeyPress  and  KeyRelease  may  be  used,  or  use  one  of 
the  abbreviations  shown  in  the  following  table. 


Abbreviation 


Key 

KeyDown 

Ctrl 

Meta 

Shift 

KeyUp 


Description 


Key  pressed 

Key  pressed 

KeyPress  with  Ctrl  modifier 

KeyPress  with  Meta  modifier 

KeyPress  with  Shift  modifier 

Key  released 


To  execute  an  action  in  response  to  the  press  or  release  of  an  individual  key,  you  can  use  any  of 
the  above  abbreviations  in  combination  with  a  detail.  For  example,  in  the  translation: 

<Key>a :    append () 

the  append  action  is  invoked  when  the  key  "a"  is  pressed,  regardless  of  which  modifiers  are 
being  held.  For  more  information  on  how  to  use  translations  to  manage  key  events,  see  Chapter 
7,  Events,  Translations,  and  Accelerators,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming 
Manual. 

Select  With 

Each  type  of  keyboard  event  may  be  selected  separately  with  KeyPressMask  and  Key- 
ReleaseMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XKeyEvent  xkey; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type;  /• 
unsigned  long  serial;  A 

Bool  send_event;  /: 

Display  ^display;  /' 

Window  window;  /; 

Window  root;  /' 

Window  subwindow;  /' 

Time  time;  /' 


of  event  */ 

#  of  last  request  processed  by  server  */ 

TRUE  if  this  came  from  SendEvent  request  */ 

display  the  event  was  read  from  */ 

event  window  it  is  reported  relative  to  */ 

root  window  that  the  event  occurred  on  */ 

child  window  */ 

milliseconds  */ 
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xkey 


(continued) 


KeyPress,  KeyRelease 


int  x,  y;  /*  pointer  coords  relative  to  receiving  window  */ 

int  x_root,  y_root;   /*  coordinates  relative  to  root  */ 
unsigned  int  state;   /*  modifier  key  and  button  mask  */ 
unsigned  int  keycode;  /*  server-dependent  code  for  key  */ 
Bool  same_screen;     /*  same  screen  flag  */ 

}  XKeyEvent; 

typedef  XKeyEvent  XKeyPressedEvent; 

typedef  XKeyEvent  XKeyReleasedEvent; 

Event  Structure  Members 

subwindow  If  the  source  window  is  the  child  of  the  receiving  window,  then  the  subwindow 
member  is  set  to  the  ID  of  that  child. 

time  The  server  time  when  the  button  event  occurred,  in  milliseconds.    Time  is 

declared  as  unsigned  long,  so  it  wraps  around  when  it  reaches  the  maxi 
mum  value  of  a  32-bit  number  (every  49.7  days). 

x ,    y  If  the  receiving  window  is  on  the  same  screen  as  the  root  window  specified  by 

root,  then  x  and  y  are  the  pointer  coordinates  relative  to  the  receiving  win 
dow's  origin.  Otherwise,  x  and  y  are  zero. 

When  active  button  grabs  and  pointer  grabs  are  in  effect  (see  Volume  One,  Xlib 
Programming  Manual,  Section  9.4  and  Volume  Four,  X  Toolkit  Intrinsics  Pro 
gramming  Manual,  Chapter  12,  Menus,  Gadgets,  and  Cascaded  Pop  Ups,  Sec 
tion  12.2.1),  the  coordinates  relative  to  the  receiving  window  may  not  be  within 
the  window  (they  may  be  negative  or  greater  than  window  height  or  width). 

x_root,  y_root 

The  pointer  coordinates  relative  to  the  root  window  which  is  an  ancestor  of  the 
event  window.  If  the  pointer  was  on  a  different  screen,  these  are  zero. 

state  The  state  of  all  the  buttons  and  modifier  keys  just  before  the  event,  represented 

by  a  mask  of  the  button  and  modifier  key  symbols:  ButtonlMask, 
Button2Mask,  ButtonSMask,  Button4Mask,  ButtonSMask,  Shift- 
Mask,  ControlMask,  LockMask,  ModlMask,  Mod2Mask,  ModSMask, 
Mod4Mask,  and  ModSMask. 

keycode  The  keycode  member  contains  a  server-dependent  code  for  the  key  that 
changed  state.  As  such  it  should  be  translated  into  the  portable  symbol  called  a 
keysym  before  being  used.  It  can  also  be  converted  directly  into  ASCII  with 
XLookupString.  For  a  description  and  examples  of  how  to  translate  key- 
codes,  see  Volume  One,  Section  9.1.1,  and  Volume  Four,  Section  13.4. 

Notes 

Remember  that  not  all  hardware  is  capable  of  generating  release  events,  and  that  only  the  main 
keyboard  (a-z,  A-Z,  0-9),  Shift,  and  Control  keys  are  always  found. 
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KeyPress,  KeyRelease  (continued)  xkey 

Keyboard  events  are  analogous  to  button  events,  though  of  course  there  are  many  more  keys 
than  buttons,  and  the  keyboard  is  not  automatically  grabbed  between  press  and  release. 

All  the  structure  members  have  the  same  meaning  as  described  for  ButtonPress  and 
ButtonRelease  events  except  that  button  is  replaced  by  keycode. 
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— xmap,  xunmap- 


MapNotify,  UnmapNotify 


When  Generated 

The  X  server  generates  MapNotify  and  UnmapNotify  events  when  a  window  changes  state 
from  unmapped  to  mapped  or  vice  versa.  In  most  cases,  Xt  widgets  are  mapped  in  the  final  step 
of  the  process  of  realizing  the  application,  initiated  with  xtRealizeWidget. 

Translation  Abbreviations 

In  translation  tables,  the  event  types  MapNotify  and  UnmapNotify  may  be  used,  or  use  the 
abbreviations  Map  or  Unmap. 

Select  With 

To  receive  these  events  on  a  single  window,  use  StructureNotifyMask  in  the  call  to 
XSelect Input  for  the  window.  To  receive  these  events  for  all  children  of  a  particular 
parent,  specify  the  parent  window  ID  and  use  SubstructureNotif  yMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XMapEvent  xmap; 
XUnmapEvent  xunmap; 

}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial;  /i 

Bool  send_event;      /' 

Display  *display;     /' 

Window  event; 

Window  window; 

Bool  override_redirect; 
}  XMapEvent; 


#  of  last  request  processed  by  server  */ 
TRUE  if  this  came  from  SendEvent  request 
display  the  event  was  read  from  */ 


/*  Boolean,  is  override  set  */ 


typedef  struct  { 

int  type; 

unsigned  long  serial;  / 

Bool  send_event;      / 

Display  *display;     / 

Window  event; 

Window  window; 

Bool  f rom_conf igure; 
}  XUnmapEvent; 


Event  Structure  Members 

event        The  window  that  selected  this  event 

window      The  window  that  was  just  mapped  or  unmapped. 


#  of  last  request  processed  by  server  */ 
TRUE  if  this  came  from  SendEvent  request 
display  the  event  was  read  from  */ 
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MapNotify,  UnmapNotify  (continued)  xmap,xunmap 

override_redirect  (XMapEvent  only) 

TRUE  or  FALSE.  The  value  of  the  override_redirect  attribute  of  the  window 
that  was  just  mapped. 

f  rom_conf  igure  (XUnmapEvent  only) 

TRUE  if  the  event  was  generated  as  a  result  of  a  resizing  of  the  window's  parent 
when  the  window  itself  had  a  win_gravity  of  UnmapGravity.  See  the 
description  of  the  win_gravity  attribute  in  Volume  One,  Section  4.3.4.  FALSE 
otherwise. 


X  Toolkit  Intrinsics  Reference  Manual 


— xmapping- 


MappingNotify 


When  Generated 

A  MappingNotify  event  is  sent  when  any  of  the  following  is  changed  by  another  client:  the 
mapping  between  physical  keyboard  keys  (keycodes)  and  keysyms,  the  mapping  between  mod 
ifier  keys  and  logical  modifiers,  or  the  mapping  between  physical  and  logical  pointer  buttons. 
These  events  are  triggered  by  a  call  to  XSetModifierMapping  or  XSetPointer- 
Mapping,  if  the  return  status  is  MappingSuccess,  or  by  any  call  to  XChangeKeyboard- 
Mapping. 

This  event  type  should  not  be  confused  with  the  event  that  occurs  when  a  window  is  mapped; 
that  is  a  MapNotify  event.  Nor  should  it  be  confused  with  the  KeymapNotify  event, 
which  reports  the  state  of  the  keyboard  as  a  mask  instead  of  as  a  keycode. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  MappingNotify  may  be  used,  or  use  the  abbreviation 
Mapping.  Xt  handles  MappingNotify  automatically  in  most  applications. 

To  detect  only  one  of  modifier,  keyboard,  and  pointer  mapping  changes,  use  a  translation  such 
as: 

<Mapping>Pointer :    pointerRemap ( ) 

Where  Pointer  can  also  be  Modifier  or  Keyboard. 

Select  With 

The  X  server  sends  MappingNotify  events  to  all  clients.  It  is  never  selected  and  cannot  be 
masked  with  the  window  attributes. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XMappingEvent  xmapping; 
}  XEvent; 

Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial, 
Bool  send_event; 
Display  *display; 
Window  window; 
int  request; 


int  f irst_keycode; 
int  count; 
}  XMappingEvent; 


#  of  last  request  processed  by  server  */ 

TRUE  if  this  came  from  SendEvent  request 

display  the  event  was  read  from  */ 

unused  */ 

one  of  MappingModif ier,  MappingKeyboard, 

MappingPointer  */ 

first  keycode  */ 

range  of  change  with  f irst_keycode*/ 
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MappingNotify  (continued)  xmapping 

Event  Structure  Members 

request  The  kind  of  mapping  change  that  occurred:  MappingModif  ier  for  a  successful 
XSetModifierMapping  (keyboard  Shift,  Lock,  Control,  Meta  keys), 
MappingKeyboard  for  a  successful  XChangeKeyboardMapping  (other 
keys),  and  MappingPointer  for  a  successful  XSetPointerMapping 
(pointer  button  numbers). 

first_keycode 

If  the  request  member  is  MappingKeyboard  or  MappingModif  ier,  then 
f  irst_keycode  indicates  the  first  in  a  range  of  keycodes  with  altered  map 
pings.  Otherwise  it  is  not  set 

count  If  the  request  member  is  MappingKeyboard  or  MappingModif  ier,  then 
count  indicates  the  number  of  keycodes  with  altered  mappings.  Otherwise  it  is 
not  set 

Notes 

If  the  request  member  is  MappingKeyboard,  clients  should  call  XRef reshKeyboard- 

Mapping. 

The  normal  response  to  a  request  member  of  MappingPointer  or  MappingModif  ier 
is  no  action.  This  is  because  the  clients  should  use  the  logical  mapping  of  the  buttons  and  mod 
ifiers  to  allow  the  user  to  customize  the  keyboard  if  desired.  If  the  application  requires  a  partic 
ular  mapping  regardless  of  the  user's  preferences,  it  should  call  XGetModif  ierMapping  or 
XGetPointerMapping  to  find  out  about  the  new  mapping. 
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. /  MapRequest 

— xmaprequest ' 

When  Generated 

A  MapRequest  event  occurs  when  the  functions  XMapRaised  and  XMapWindow  are 
called. 

This  event  differs  from  MapNotif  y  in  that  it  delivers  the  parameters  of  the  request  before  it  is 
carried  out.  This  gives  the  client  that  selects  this  event  (usually  the  window  manager)  the 
opportunity  to  revise  the  size  or  position  of  the  window  before  executing  the  map  request  itself 
or  to  deny  the  request.  (MapNotif  y  indicates  the  final  outcome  of  the  request.) 

Translation  Abbreviations 

In  translation  tables,  the  event  type  MapRequest  may  be  used,  or  use  the  abbreviation  Map- 
Req. 

Select  With 

This  event  is  selected  by  specifying  the  window  ID  of  the  parent  of  the  receiving  window  with 
SubstructureRedirectMask.  (In  addition,  the  override_redirect  member  of  the 
xsetwindowAt tributes  structure  for  the  specified  window  must  be  FALSE.) 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XMapRequestEvent  xmaprequest; 
}  XEvent; 

Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 
Bool  send_event;      /*  TRUE  if  this  came  from  SendEvent  request  */ 
Display  *display;     /*  display  the  event  was  read  from  */ 
Window  parent; 
Window  window; 

}  XMapRequestEvent; 

Event  Structure  Members 

parent      The  ID  of  the  parent  of  the  window  being  mapped. 

window      The  ID  of  the  window  being  mapped. 
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MotionNotify  V 


•xmotion  — 


When  Generated 

A  MotionNotify  event  reports  that  the  user  moved  the  pointer  or  that  a  program  warped  the 
pointer  to  a  new  position  within  a  single  window. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  MotionNotify  may  be  used,  or  use  one  of  the  abbrevia 
tions  shown  in  the  following  table. 


Abbreviation 


Motion 

PtrMoved 

MouseMoved 

BtnMotion 

BtnlMotion 

Btn2Motion 

Btn3Motion 

Btn4Motion 

BtnSMotion 


Description 


Pointer  moved 
Pointer  moved 
Pointer  moved 

Pointer  moved  with  any  button  held  down 
Pointer  moved  with  button  1  held  down 
Pointer  moved  with  button  2  held  down 
Pointer  moved  with  button  3  held  down 
Pointer  moved  with  button  4  held  down 
Pointer  moved  with  button  5  held  down 


To  execute  an  action  in  response  to  motion  hint  events  or  normal  motion  events,  you  can  use 
any  of  the  abbreviations  above,  together  with  a  detail.  For  example,  in  the  translation: 

<Motion>Normal :      all   Positions () 

theallPositions  action  will  be  called  with  all  the  motion  events.  On  the  other  hand,  if  you 
specify: 

<Motion>Hint :       lastPosition ( ) 

the  lastPosition  action  will  be  called  much  less  frequently — only  when  the  pointer  leaves 
the  window  or  when  a  key  or  button  changes  state.  The  default,  when  you  don't  specify  a 
detail,  is  to  get  normal  motion  events. 

The  Core  widget  field  compressjmotion  also  determines  whether  the  widget  gets  all 
motion  events  or  only  periodic  position  updates.  For  more  information,  see  Chapter  8,  More 
Input  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual. 

Select  With 

This  event  is  selected  with  PointerMotionMask,  PointerMotionHintMask, 
ButtonMotionMask,  ButtonlMotionMask,  Button2MotionMask,  ButtonS- 
MotionMask,  Button4MotionMask,  and  ButtonSMotionMask.  These  masks  deter 
mine  the  specific  conditions  under  which  the  event  is  generated. 
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xmotion 


(continued) 


MotionNotify 


of  event  */ 

#  of  last  request  processed  by  server  */ 

TRUE  if  this  came  from  SendEvent  request  */ 

display  the  event  was  read  from  */ 

event  window  it  is  reported  relative  to  */ 

root  window  that  the  event  occurred  on  */ 

child  window  */ 

milliseconds  */ 

pointer  coords  relative  to  receiving  window 

coordinates  relative  to  root  */ 

button  and  modifier  key  mask  */ 

is  this  a  motion  hint  */ 

same  screen  flag  */ 


XEvent  Structure  Name 

typedef  union  _XEvent  { 

XMotionEvent  xmotion; 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type;  /' 

unsigned  long  serial;  /: 

Bool  send_event;  /' 

Display  *display;  /' 

Window  window;  /' 

Window  root;  /' 

Window  subwindow;  /: 

Time  time;  /• 

int  x,  y;  /: 

int  x_root,  y_root;  /' 

unsigned  int  state;  /' 

char  is_hint;  /• 

Bool  same_screen;  /' 
}  XMotionEvent; 
typedef  XMotionEvent  XPointerMovedEvent; 

Event  Structure  Members 

subwindow   If  the  source  window  is  the  child  of  the  receiving  window,  then  the  subwindow 
member  is  set  to  the  ID  of  that  child. 

time  The  server  time  when  the  button  event  occurred,  in  milliseconds.    Time  is 

declared  as  unsigned  long,  so  it  wraps  around  when  it  reaches  the  maximum 
value  of  a  32  bit  number  (every  49.7  days). 

x,    y  If  the  receiving  window  is  on  the  same  screen  as  the  root  window  specified  by 

root,  then  x  and  y  are  the  pointer  coordinates  relative  to  the  receiving  win 
dow's  origin.  Otherwise,  x  and  y  are  zero. 

When  active  button  grabs  and  pointer  grabs  are  in  effect  (see  Section  9.4  in  Vol 
ume  One,  Xlib  Programming  Manual,  and  Section  12.2.1  in  Volume  Four,  X 
Toolkit  Intrinsics  Programming  Manual)  the  coordinates  relative  to  the  receiv 
ing  window  may  not  be  within  the  window  (they  may  be  negative  or  greater  than 
window  height  or  width). 

x_root,  y_root 

The  pointer  coordinates  relative  to  the  root  window  which  is  an  ancestor  of  the 
event  window.  If  the  pointer  was  on  a  different  screen,  these  are  zero. 
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MotionNotify 


(continued) 


xmotion 


state  The  state  of  all  the  buttons  and  modifier  keys  just  before  the  event,  represented 

by  a  mask  of  the  button  and  modifier  key  symbols:  ButtonlMask, 
Button2Mask,  ButtonSMask,  Button4Mask,  ButtonSMask,  Shift- 
Mask,  ControlMask,  LockMask,  ModlMask,  Mod2Mask,  ModSMask, 
Mod4Mask,  and  ModSMask. 

is_hint  Either  the  constant  NotifyNormal  or  NotifyHint.  NotifyHint  indi 
cates  that  the  PointerMotionHintMask  was  selected.  In  this  case,  just  one 
event  is  sent  when  the  mouse  moves,  and  the  current  position  can  be  found  by 
calling  XQueryPointer,  or  by  examining  the  motion  history  buffer  with 
XGetMotionEvents,  if  a  motion  history  buffer  is  available  on  the  server. 
NotifyNormal  indicates  that  the  event  is  real,  but  it  may  not  be  up  to  date 
since  there  may  be  many  more  later  motion  events  on  the  queue. 

same_screen 

Indicates  whether  the  pointer  is  currently  on  the  same  screen  as  this  window. 
This  is  always  TRUE  unless  the  pointer  was  actively  grabbed  before  the  auto 
matic  grab  could  take  place. 


Notes 


If  the  processing  you  have  to  do  for  every  motion  event  is  fast,  you  can  probably  handle  all  of 
them  without  requiring  motion  hints.  However,  if  you  have  extensive  processing  to  do  for  each 
one,  you  might  be  better  off  using  the  hints  and  calling  XQueryPointer  or  using  the  history 
buffer  if  it  exists.  XQueryPointer  is  a  round-trip  request,  so  it  can  be  slow. 

EnterNotify  and  LeaveNotify  events  are  generated  instead  of  MotionEvents  if  the 
pointer  starts  and  stops  in  different  windows. 
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— xproperty- 


PropertyNotify 


When  Generated 

A  PropertyNotify  event  indicates  that  a  property  of  a  window  has  changed  or  been 
deleted.  This  event  can  also  be  used  to  get  the  current  server  time  (by  appending  zero-length 
data  to  a  property).  PropertyNotify  events  are  generated  by  XChangeProperty, 
XDeleteProperty,  XGetWindowProperty,orXRotateWindowProperties. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  PropertyNotify  may  be  used,  or  use  the  abbreviation 

Prop. 

To  be  notified  of  a  change  in  a  particular  property,  use  the  property  name  as  a  detail.  For 
example,  the  translation: 

<Prop>PRIMARY:   status  () 

results  in  the  status  action  being  called  when  the  PRIMARY  property  (used  in  selections)  is 
changed. 

Select  With 

This  event  is  selected  with  PropertyChangeMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XPropertyEvent  xproperty; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial, 

Bool  send_event; 

Display  ^display; 

Window  window; 

Atom  atom; 

Time  time; 

int  state; 
}  XPropertyEvent; 


/*  #  of  last  request  processed  by  server  */ 
/*  TRUE  if  this  came  from  SendEvent  request  */ 
/*  display  the  event  was  read  from  */ 


/*  NewValue,  Deleted  */ 


Event  Structure  Members 

window      The  window  whose  property  was  changed,  not  the  window  that  selected  the  event. 

atom          The  property  that  was  changed. 

state         Either  PropertyNewValue  or  PropertyDelete.  Whether  the  property  was 
changed  to  a  new  value  or  deleted. 

time  The  time  member  specifies  the  server  time  when  the  property  was  changed. 


X  Toolkit  Intrinsics  Reference  Manual 


695 


ReparentNotify  , xreparem_ 

When  Generated 

A  ReparentNotify  event  reports  when  a  client  successfully  reparents  a  window. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  ReparentNotify  may  be  used,  or  use  the  abbreviation 

Reparent. 

Select  With 

This  event  is  selected  with  SubstructureNotif  yMask  by  specifying  the  window  ID  of  the 
old  or  the  new  parent  window  or  with  StructureNotifyMask  by  specifying  the  window 
ID. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XReparentEvent  xreparent; 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 

Bool  send_event;      /*  TRUE  if  this  came  from  SendEvent  request  */ 

Display  *display;     /*  display  the  event  was  read  from  */ 

Window  event; 

Window  window;  , 

Window  parent; 

int  x,  y; 

Bool  override_redirect ; 
}  XReparentEvent; 

Event  Structure  Members 

window      The  window  whose  parent  window  was  changed. 

parent      The  new  parent  of  the  window. 

x,    y  The  coordinates  of  the  upper-left  pixel  of  the  window's  border  relative  to  the  new 

parent  window's  origin. 

over ride_redi  rect 

The  override_redirect  attribute  of  the  reparented  window.  If  TRUE,  it  indi 
cates  that  the  client  wants  this  window  to  be  immune  to  meddling  by  the  window 
manager.  Window  managers  normally  should  not  have  reparented  this  window  to 
begin  with. 
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/  ResizeRequest 

— xresizerequest ' 

When  Generated 

A  ResizeRequest  event  reports  another  client's  attempt  to  change  the  size  of  a  window. 
The  X  server  generates  this  event  type  when  another  client  calls  XConf  igureWindow, 
XResizeWindow,  or  XMoveResizeWindow.  If  this  event  type  is  selected,  the  window  is 
not  resized.  This  gives  the  client  that  selects  this  event  (usually  the  window  manager)  the 
opportunity  to  revise  the  new  size  of  the  window  before  executing  the  resize  request  or  to  deny 
the  request  itself. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  ResizeRequest  may  be  used,  or  use  the  abbreviation 

ResReq. 

Select  With 

To  receive  this  event  type,  specify  a  window  ID  and  pass  ResizeRedirectMask  as  part  of 
the  event_mask  argument  to  XSelect Input.  Only  one  client  can  select  this  event  on  a 
particular  window.  When  selected,  this  event  is  triggered  instead  of  resizing  the  window. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XResizeRequest Event  xresizerequest; 
}  XEvent; 

Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 
Bool  send_event;      /*  TRUE  if  this  came  from  SendEvent  request  */ 
Display  *display;     /*  display  the  event  was  read  from  */ 
Window  window; 
int  width,  height; 

}  XResizeRequestEvent ; 

Event  Structure  Members 

window  The  window  whose  size  another  client  attempted  to  change. 

width ,    height    The  requested  size  of  the  window,  not  including  its  border. 
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SelectionClear  \ 


•xselectionclear — 


When  Generated 

A  SelectionClear  event  reports  to  the  current  owner  of  a  selection  that  a  new  owner  is 
being  defined. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  SelectionClear  may  be  used,  or  use  the  abbreviation 

SelClr. 

However,  all  selection  events  are  normally  handled  automatically  by  Xt's  selection  mechanism, 
and  therefore  no  translations  are  needed. 

When  translations  are  used,  the  name  of  the  selection  property  can  be  specified  as  a  detail  (see 

PropertyNotify). 

Select  With 

This  event  is  not  selected.  It  is  sent  to  the  previous  selection  owner  when  another  client  calls 
XSetSelectionOwner  for  the  same  selection. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XSelectionClear Event  xselectionclear; 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type;  r, 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 
Bool  send_event;      /*  TRUE  if  this  came  from  SendEvent  request  */ 
Display  *display;     /*  display  the  event  was  read  from  */ 
Window  window; 
Atom  selection; 
Time  time; 

}  XSelectionClearEvent; 

Event  Structure  Members 

window  The  window  that  is  receiving  the  event  and  losing  the  selection. 

selection  The  selection  atom  specifying  the  selection  that  is  changing  ownership. 

time  The  last-change  time  recorded  for  the  selection. 
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.  SelectionNotify 

— xselection ' 

When  Generated 

A  SelectionNotify  event  is  sent  only  by  clients,  not  by  the  server,  by  calling  XSend- 
Event.  The  owner  of  a  selection  sends  this  event  to  a  requestor  (a  client  that  calls 
XConvertSelection  for  a  given  property)  when  a  selection  has  been  converted  and  stored 
as  a  property  or  when  a  selection  conversion  could  not  be  performed  (indicated  with  property 

None). 

Translation  Abbreviations 

In  translation  tables,  use  the  event  type  SelectionNotify,  or  its  abbreviation  Select. 

However,  all  selection  events  are  normally  handled  automatically  by  Xt's  selection  mechanism, 
and  therefore  no  translations  are  needed. 

When  translations  are  used,  the  name  of  the  selection  property  can  be  specified  as  a  detail  (see 
PropertyNotify). 

Select  With 

There  is  no  event  mask  for  SelectionNotify  events,  and  they  are  not  selected  with 
XSelectlnput.  Instead  XSendEvent  directs  the  event  to  a  specific  window,  which  is 
given  as  a  window  ID:  PointerWindow,  which  identifies  the  window  the  pointer  is  in,  or 
InputFocus,  which  identifies  the  focus  window. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XSelectionEvent  xselection; 
}  XEvent; 

Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial;  /*  f  of  last  request  processed  by  server  */ 
Bool  send_event;      /*  TRUE  if  this  came  from  SendEvent  request  */ 
Display  *display;     /*  display  the  event  was  read  from  */ 
Window  requestor;     /*  must  be  next  after  type  */ 
Atom  selection; 
Atom  target; 

Atom  property;        /*  Atom  or  None  */ 
Time  time; 

}  XSelectionEvent; 

Event  Structure  Members 

This  structure's  members  have  the  values  specified  in  the  XConvertSelection  call  that 
triggers  the  selection  owner  to  send  this  event,  except  that  the  property  member  either 
returns  the  atom  specifying  a  property  on  the  requestor  window  with  the  data  type  specified  in 
target,  or  it  returns  None,  indicating  that  the  data  could  not  be  converted  into  the  target 
type. 
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SelectionRequest  \ 


•xselectionrequest — 


When  Generated 

A  SelectionRequest  event  is  sent  to  the  owner  of  a  selection  when  another  client  requests 
the  selection  by  calling  XConvertSelection. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  SelectionRequest  may  be  used,  or  use  the  abbrevia 
tion  SelReq. 

However,  all  selection  events  are  normally  handled  automatically  by  Xt's  selection  mechanism, 
and  therefore  no  translations  are  needed. 

When  translations  are  used,  the  name  of  the  selection  property  can  be  specified  as  a  detail  (see 

PropertyNotify). 

Select  With 

There  is  no  event  mask  for  SelectionRequest  events,  and  they  are  not  selected  with 

XSelectlnput. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XSelectionRequestEvent  xselectionrequest; 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type;  , 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 
Bool  send_event;      /*  TRUE  if  this  came  from  SendEvent  request  */ 
Display  ^display;     /*  display  the  event  was  read  from  */ 
Window  owner;         /*  must  be  next  after  type  */ 
Window  requestor; 
Atom  selection; 
Atom  target; 
Atom  property/ 
Time  time; 

}  XSelectionRequestEvent; 

Event  Structure  Members 

The  members  of  this  structure  have  the  values  specified  in  the  XConvertSelection  call 
that  triggers  this  event. 

The  owner  should  convert  the  selection  based  on  the  specified  target  type,  if  possible.  If  a 
property  is  specified,  the  owner  should  store  the  result  as  that  property  on  the  requestor  win 
dow,  and  then  send  a  SelectionNotif  y  event  to  the  requestor  by  calling  xSendEvent.  If 
the  selection  cannot  be  converted  as  requested,  the  owner  should  send  a  SelectionNotif  y 
event  with  property  set  to  the  constant  None. 
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—xvisibility- 


VisibilityNotify 


When  Generated 

A  VisibilityNotify  event  reports  any  change  in  the  visibility  of  the  specified  window. 
This  event  type  is  never  generated  on  windows  whose  class  is  Input  Only.  All  of  the  win 
dow's  subwindows  are  ignored  when  calculating  the  visibility  of  the  window. 

Translation  Abbreviations 

In  translation  tables,  the  event  type  VisibilityNotify  may  be  used,  or  use  the  abbrevia 
tion  visible. 

Most  widgets  do  not  need  to  provide  a  translation  for  this  event,  because  the  Core  widget  field 
visible_interest  provides  a  simplified  form  of  the  same  information.  For  more  informa 
tion,  see  Chapter  8,  More  Input  Techniques,  in  Volume  Four,  X  Toolkit  Intrinsics  Program 
ming  Manual. 

Select  With 

This  event  is  selected  with  VisibilityChangeMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XVisibilityEvent  xvisibility; 
}  XEvent; 


Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial, 
Bool  send_event; 
Display  *display; 
Window  window; 
int  state; 


}  XVisibilityEvent; 


/*  #  of  last  request  processed  by  server  */ 

/*  TRUE  if  this  came  from  SendEvent  request 

/*  display  the  event  was  read  from  */ 

/*  VisibilityUnobscured, */ 

/*  VisibilityPartiallyObscured,  or  */ 

/*  VisibilityFullyObscured  */ 


Event  Structure  Members 

state  A  symbol  indicating  the  final  visibility  status  of  the  window:  Visibility 
Unobscured,  VisibilityPartiallyObscured,  or  Visibility 
FullyObscured. 

Notes 

Table  C-6  lists  the  transitions  that  generate  VisibilityNotify  events  and  the  correspond 
ing  state  member  of  the  XVisibilityEvent  structure. 
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VisibilityNotify 


(continued) 


xvisibility 


Table  C-6.  The  State  Element  of  the  XVisibilityEvent  Structure 


Visibility  Status  Before 


Visibility  Status  After 


State  Member 


Partially  obscured,  fully 
obscured,  or  not  view 
able 

Viewable  and  com 
pletely  unobscured,  or 
not  viewable 

Viewable  and  com 
pletely  unobscured,  or 
viewable  and  partially 
obscured,  or  not  view 
able 


Viewable  and  com 
pletely  unobscured 

Viewable   and  partially 
obscured 

Viewable      and      fully 
obscured 


VisibilityUnobscured 


VisibilityPartially- 
Obscured 


VisibilityFully- 
Obscured 
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Standard  Errors  and  Warnings 


The  two  sections  below  summarize  all  errors  and  warnings  that  the  Toolkit  can  generate.  The 
information  has  this  form: 


Message  Name 

Message  Type 


Default  message 


Note  that  many  messages  have  more  than  one  type;  however,  all  Toolkit  errors  and  warnings 
have  class  XtToolkitError. 


Error  Messages 


allocError 

calloc 
malloc 
realloc 

communicationError 

select 

internalError 

shell 

invalidArgCount 

xtGetValues 
xtSetValues 

invalidClass 

constraint Set Value 

xtAppCreateShell 

xtCreatePopupShell 

xtCreateWidget 

xtPopdown 

xtPopup 

invalidDimension 

xt Great eWindow 
shellRealize 


Cannot  perform  calloc 
Cannot  perform  malloc 
Cannot  perform  realloc 


Select  failed 


Shell's  window  manager  interaction  is  broken 


Argument  count  >  0  on  NULL  argument  list  in  XtGetValues 
Argument  count  >  0  on  NULL  argument  list  in  XtSetValues 


Subclass  of  Constraint  required  in  CallConstraintSetValues 
XtAppCreateShell  requires  non-NULL  widget  class 
XtCreatePopupShell  requires  non-NULL  widget  class 
XtCreateWidget  requires  non-NULL  widget  class 
XtPopdown  requires  a  subclass  of  shellWidgetClass 
XtPopup  requires  a  subclass  of  shellWidgetClass 


Widget  %s  has  zero  width  and/or  height 
Shell  widget  %s  has  zero  width  and/or  height 
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invalidDisplay 

xtlnitialize 


Cannot  open  display 


invalidGeometryManager 

xtMakeGeometryRequest  XtMakeGeometryRequest  -  parent  has  no  geometry  manger 

invalidParameter 

removePopupFromParent  RemovePopupFromParent  requires  non-NULL  popuplist 

xt Addl nput  Invalid  condition  passed  to  XtAddlnput 


invalidParameters 

xtMenuPopupAction 
xtmenuPopdown 

invalidParent 

realize 

xtCreatePopupShell 

xtCreateWidget 

xtMakeGeometryRequest 

xtMakeGeometryRequest 

xtManageChildren 

xtUnmanageChi Idren 

invalidPopup 

xtMenuPopup 
xtMenuPopup 

invalidProcedure 

inheritanceProc 
realizeProc 

invalidWindow 

eventHandler 

missingEvent 

shell 

noAppContext 

widget ToAppli cat ion- 
Context 

no  Per  I)  is  pi  ay 

closeDisplay 
getPerDi splay 


MenuPopup  wants  exactly  one  argument 
XtMenuPopdown  called  with  num_params  !=  0  or  1 


Application  shell  is  not  a  windowed  widget? 
XtCreatePopupShell  requires  non-NULL  parent 
XtCreateWidget  requires  non-NULL  parent 
XtMakeGeometryRequest  -  NULL  parent.  Use  SetValues  instead 
XtMakeGeometryRequest  -  parent  not  composite 
Attempt  to  manage  a  child  when  parent  is  not  Composite 
Attempt  to  unmanage  a  child  when  parent  is  not  Composite 


Cannot  find  pop  up  in  _XtMenuPopup 
Cannot  find  pop  up  in  _XtMenuPopup 


Unresolved  inheritance  operation 
No  realize  class  procedure  defined 

Event  with  wrong  window 

Events  are  disappearing  from  under  Shell 

Couldn't  find  ancestor  with  display  information 


Couldn't  find  per  display  information 
Couldn't  find  per  display  information 


noSelectionProperties 

f  reeSelectionProperty     Internal  error:  no  selection  property  context  for  display 


nulIProc 

insertChild 

subclassMismatch 

xtCheckSubclass 


NULL  insert_child  procedure 

Widget  class  %s  found  when  subclass  of  %s  expected:  %s 
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translationError 

mergingTablesWithCycles  Trying  to  merge  translation  tables  with  cycles,  and  cannot  resolve 

this  cycle 


wrongParameters 

cvtlntOrPixelToXColor 
cvtStringToCursor 
cvtStringToFont 
cvtStringToFont Struct 
cvtStringToPixel 


Pixel-to-color  conversion  needs  screen  and  colormap  arguments 
String-to-cursor  conversion  needs  screen  argument 
String-to-font  conversion  needs  screen  argument 
String-to-cursor  conversion  needs  screen  argument 
String-to-pixel  conversion  needs  screen  and  colormap  arguments 


Warning  Messages 

ambigiousParent 

xtManageChildren 
xtUnmanageChildren 

communicationError 

windowManager 

conversionError 

string 

dispIayError 

invalidDi splay 

grabError 

grabDestroyCallback 
grabDestroyCallback 
xtRemoveGrab 

initialization  Error 

xtlnitialize 

invalidArgCount 

getResources 

invalidCallbackList 

xtAddCallbacks 

xtCallCallback 

xtOverrideCallback 

xtRemoveAHCallback 

xtRemoveCallbacks 

invalidChild 

xtManageChildren 
xtUnmanageChildren 

invalidDepth 

setValues 


Not  all  children  have  same  parent  in  XtManageChildren 
Not  all  children  have  same  parent  in  XtUnmanageChildren 


Window  Manager  is  confused 


Cannot  convert  string  "%s"  to  type  "%s" 


Cannot  find  display  structure 


XtAddGrab  requires  exclusive  grab  if  spring_loaded  is  TRUE 
XtAddGrab  requires  exclusive  grab  if  spring_loaded  is  TRUE 
XtRemoveGrab  asked  to  remove  a  widget  not  on  the  grab  list 


Initializing  Resource  Lists  twice 
Argument  count  >  0  on  NULL  argument  list 

Cannot  find  callback  list  in  XtAddCallbacks 
Cannot  find  callback  list  in  XtCallCallbacks 
Cannot  find  callback  list  in  XtOverrideCallbacks 
Cannot  find  callback  list  in  XtRemoveAllCallbacks 
Cannot  find  callback  list  in  XtRemoveCallbacks 


NULL  child  passed  to  XtManageChildren 
NULL  child  passed  to  XtUnmanageChildren 


Cannot  change  widget  depth 
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invalidGeometry 

xtMakeGeomet  ryRequest      Shell  subclass  did  not  take  care  of  geometry  in  XtSetValues 

invalidParameters 

compi leAccelerator s  String  to  AcceleratorTable  needs  no  extra  arguments 

compileTranslations  String  to  TranslationTable  needs  no  extra  arguments 

mergeTranslations  MergeTM  to  TranslationTable  needs  no  extra  arguments 

invalidParent 

xtCopyFromParent  CopyFromParent  must  have  non-NULL  parent 

invalidPopup 

un suppo r t edope  ration        Pop-up  menu  creation  is  only  supported  on  ButtonPress  or  Enter- 
Notify  events 

invalidProcedure 

deleteChild  NULL  delete_child  procedure  in  XtDestroy 

inputHandler  XtRemovelnput:  Input  handler  not  found 

set   values_almost  set_values_almost  procedure  shouldn't  be  NULL 

invalidResourceCount 

getResources  Resource  count  >  0  on  NULL  resource  list 

invalidResourceName 

computeArgs  Cannot  find  resource  name  %s  as  argument  to  conversion 

invalidShell 

xtTranslateCoords  Widget  has  no  shell  ancestor 

invalidSizeOverride 

xtDependencies  Representation  size  %d  must  match  superclass's  to  override  %s 

invalidTypeOverride 

xtDependencies  Representation  type  %s  must  match  superclass's  to  override  %s 

invalidWidget 

removePopupFromParent      RemovePopupFromParent, widget  not  on  parent  list 

noColormap 

cvtStringToPixel  Cannot  allocate  colormap  entry  for  "%s" 

registerWindowError 

xtRegi  sterWindow  Attempt  to  change  already  registered  window 

xtUnregisterWindow  Attempt  to  unregister  invalid  window 

translation  error 

nullTable  Cannot  remove  accelerators  from  NULL  table 

nul liable  Tried  to  remove  non-existant  accelerators 

translationError 

ambigiousActions  Overriding  earlier  translation  manager  actions 

mergingNul  ITable  Old  translation  table  was  null,  cannot  modify 

nul  1  Table  Cannot  translate  event  through  NULL  table 

unboundActions  Actions  not  found:  %s 

xtTranslatelnitialize  Initializing  Translation  manager  twice 
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transIationParseError 

showLine 

parseError 

parseString 

typeConversionError 

noConverter 

versionMismatch 

widget 

wrongParameters 

cvtlntToBool 

cvtlntToBoolean 

cvtlntToFont 

cvtlntToPixel 

cvtlntToPixmap 

cvtlntToShort 

cvtStringToBool 

cvtStringToBoolean 

cvtStringToDi splay 

cvtStringToFile 

cvtStringToInt 

cvtStringToShort 

cvtStringToUnsignedChar 

cvtXColorToPixel 


...  found  while  parsing  "%s" 
Translation  table  syntax  error:  %s 
Missing  "\" 


No  type  converter  registered  for  "%s"  to  "%s"  conversion 


Widget  class  %s  version  mismatch:  widget  %d  vs.  intrinsics  %d 

Integer-to-Bool  conversion  needs  no  extra  arguments 
Integer-to-Boolean  conversion  needs  no  extra  arguments 
Integer-to-Font  conversion  needs  no  extra  arguments 
Integer-to-Pixel  conversion  needs  no  extra  arguments 
Integer-to-Pixmap  conversion  needs  no  extra  arguments 
Integer-to-Short  conversion  needs  no  extra  arguments 
String -to-Bool  conversion  needs  no  extra  arguments 
String-to-Boolean  conversion  needs  no  extra  arguments 
String-to-Display  conversion  needs  no  extra  arguments 
String-to-File  conversion  needs  no  extra  arguments 
String-to-integer  conversion  needs  no  extra  arguments 
String-to-integer  conversion  needs  no  extra  arguments 
String-to-integer  conversion  needs  no  extra  arguments 
Color-to-Pixel  conversion  needs  no  extra  arguments 
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Resource  File  Format 


A  resource  file  contains  text  representing  the  default  resource  values  for  an  application  or  set 
of  applications. 

The  format  of  resource  files  is  defined  in  Xlib  -  C  Language  X  Interface  and  is  reproduced 
here  for  convenience  only. 

The  format  of  a  resource  specification  is: 

ResourceLine  =  Comment  I  ResourceSpec 

Comment  =  "!"  string  I  <empty  lino 

ResourceSpec  =  WhiteSpace  ResourceName  WhiteSpace  ":"  WhiteSpace  value 

ResourceName  =  [Binding]  ComponentName  {Binding  ComponentName) 

Binding  =  "."  I  "*" 

WhiteSpace  =  {" "  I  "\t") 

ComponentName  =  {"A"-"Z"  I  "a"-"z"  I  "0"-"9"  I  "_"  I  "-"} 

value  =  string 

string  =  {<any  character  not  including  "\n">} 

where  (...)  means  zero  or  more  occurrences  of  the  enclosed  elements. 

If  the  last  character  on  a  line  is  a  backslash  (\),  that  line  is  assumed  to  continue  on  the  next 
line. 

To  include  a  newline  character  in  a  string,  use  "\n".  To  include  arbitrary  octets  in  a  string, 
use  the  4-character  sequence  "Nnnn"  where  nnn  is  the  numeric  value  of  the  octet  specified  as 
an  octal  constant.  For  example,  a  value  containing  a  NULL  byte  may  be  stored  by  including 
'  '\000"  in  the  string. 
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Translation  Table  Syntax 


Notation 

Syntax  is  specified  in  EBNF  notation  with  the  following  conventions: 

[  a  ]      Means  either  nothing  or '  'a' ' 

{  a  }     Means  zero  or  more  occurrences  of '  'a' ' 

All  terminals  are  enclosed  in  double  quotation  masks  ("  ").   Informal  descriptions  are 
enclosed  in  angle  brackets  (<  >). 


Syntax 

The  translation  table  file  has  the  following  syntax: 

translationTable       =  [  directive  ]  {  production  } 

directive  =  { "^replace"  I  "^override"  I  "#augment"  }  "\n" 

production  =  Ihs  ":"  rhs  "\n" 

Ihs  =  ( event  I  keyseq )  { ","  (event  I  keyseq) } 

keyseq  =  """  keychar  {keychar}  " 

keychar  =  [  "*"  I  "$"  I  "V  ]  <ISO  Latin  1  character 

event  =  [modifierjist]  "<"event_type">"  [ "("  count["+"]  ")"  ]  {detail} 

modifierjist  =  ( ["!"]  [":"]  {modifier} )  I  "None" 

modifier  =  ["""]  modifier_name 

count  =  ("1"  I  "2"  I  "3"  I  "4"  I   ...) 

modifier_name  =  "@"  <keysym>  I  <see  ModifierNames  table  below> 

event_type  =  <see  Event  Types  table  below> 

detail  =  <event  specific  details> 

rhs  =  {  name "("  [params] ")" ) 

name  =  namechar  {  namechar  } 

namechar  =  { "a"-"z"  I  "A"-"Z"  I  "0"-"9"  I  "_"  I  "-" } 

params  =  string  {","  string}. 

string  =  quoted_string  I  unquoted_string 
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quoted_string  =  """  {<Latin  1  character)  

unquoted_string       =  {<Latin  1  character  except  space,  tab, ",",  newline,  ")">} 

It  is  often  convenient  to  include  newlines  in  a  translation  table  to  make  it  more  readable.  In 
C,  indicate  a  newline  with  a  "\n": 

"<BtnlDown>:      DoSomething {) \n\ 
<Btn2Down>:       DoSomethingElse {) " 


Modifier  Names 

The  modifier  field  is  used  to  specify  normal  X  keyboard  and  button  modifier  mask  bits.  Mod 
ifiers  are  legal  on  event  types  KeyPress,  KeyRelease,  ButtonPress,  Button- 
Release,  MotionNotify,  EnterNotify,  LeaveNotify,  and  their  abbreviations; 
however,  parsing  a  translation  table  that  contains  modifiers  for  any  other  events  generates  an 
error. 

•  If  the  modif  ier_list  has  no  entries  and  is  not  None,  it  means  "don't  care"  on  all 
modifiers. 

•  If  an  exclamation  point  (!)  is  specified  at  the  beginning  of  the  modifier  list,  it  means  that 
the  listed  modifiers  must  be  in  the  correct  state  and  no  other  modifiers  can  be  asserted. 

•  If  any  modifiers  are  specified  and  an  exclamation  point  (!)  is  not  specified,  it  means  that 
the  listed  modifiers  must  be  in  the  correct  state  and  "don't  care"  about  any  other  modifi 
ers. 

•  If  a  modifier  is  preceded  by  a  tilde  (~),  it  means  that  that  modifier  must  not  be  asserted. 

•  If  None  is  specified,  it  means  no  modifiers  can  be  asserted. 

•  If  a  colon  (:)  is  specified  at  the  beginning  of  the  modifier  list,  it  directs  the  Intrinsics  to 
apply  any  standard  modifiers  in  the  event  to  map  the  event  keycode  into  a  keysym.  The 
default  standard  modifiers  are  Shift  and  Lock,  with  the  interpretation  as  defined  in  Vol 
ume  Zero,  X  Protocol  Reference  Manual.  The  resulting  keysym  must  exactly  match  the 
specified  keysym,  and  the  nonstandard  modifiers  in  the  event  must  match  the  modi- 
fierjist  For  example,  :<Key>a  is  distinct  from  :<Key>A,  and  :Shift<Key>A  is 
distinct  from  :  <Key>A. 

•  If  both  an  exclamation  point  (!)  and  a  colon  (:)  are  specified  at  the  beginning  of  the  mod 
ifier  list,  it  means  that  the  listed  modifiers  must  be  in  the  correct  state  and  that  no  other 
modifiers  except  the  standard  modifiers  can  be  asserted.  Any  standard  modifiers  in  the 
event  are  applied  as  for  colon  (:)  above. 

•  If  a  colon  (:)  is  not  specified,  no  standard  modifiers  are  applied.  Then,  for  example, 
"<Key>A"  and  "<Key>a"  are  equivalent. 

In  key  sequences,  a  circumflex  O  is  an  abbreviation  for  the  Control  modifier,  a  dollar  sign 
($)  is  an  abbreviation  for  Meta,  and  a  backslash  (\)  can  be  used  to  quote  any  character,  in 
particular  a  double  quote  ("),  a  circumflex  O,  a  dollar  sign  ($),  and  another  backslash  (\). 
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Briefly: 

No  modifiers: 

Any  modifiers: 

Only  these  modifiers: 

These  modifiers  and  any  others: 


None  <event>  detail 
<event>  detail 
!  modi  mod2  <event>  detail 
modi  mod2  <event>  detail 


The  use  of  None  for  a  modif  ier_list  is  identical  to  the  use  of  an  exclamation  point 
with  no  modifers. 

Table  F-1.  Modifier  Keys 


Modifier 

Abbreviation 

Meaning 

Ctrl 

c 

Control  modifier  bit 

Shift 

s 

Shift  modifier  bit 

Lock 

1 

Lock  modifier  bit 

Meta 

m 

Meta  key  modifier  (see  below) 

Hyper 

h 

Hyper  key  modifier  (see  below) 

Super 

su 

Super  key  modifier  (see  below) 

Alt 

a 

Alt  key  modifier  (see  below) 

Modi 

Modi  modifier  bit 

Mod2 

Mod2  modifier  bit 

Mod3 

Mod3  modifier  bit 

Mod4 

Mod4  modifier  bit 

Mod5 

ModS  modifier  bit 

Buttonl 

Buttonl  modifier  bit 

Button2 

Button2  modifier  bit 

ButtonS 

ButtonS  modifier  bit 

Button4 

Button4  modifier  bit 

Buttons 

ButtonS  modifier  bit 

None 

No  modifiers 

Any 

Any  modifier  combination 

A  key  modifier  is  any  modifier  bit  whose  corresponding  keycode  contains  the  corresponding 
left  or  right  keysym.  For  example,  m  or  Meta  means  any  modifier  bit  mapping  to  a  keycode 
whose  keysym  list  contains  XK_Meta_L  or  XK_Meta_R.  Note  that  this  interpretation  is 
for  each  display,  not  global  or  even  for  each  application  context.  The  Control,  Shift,  and 
Lock  modifier  names  refer  explicitly  to  the  corresponding  modifier  bits;  there  is  no  additional 
interpretation  of  keysyms  for  these  modifiers. 

Because  it  is  possible  to  associate  arbitrary  keysyms  with  modifiers,  the  set  of  modifier  key 
modifiers  is  extensible.  The  "@"  <keysym>  syntax  means  any  modifier  bit  whose  cor 
responding  keycode  contains  the  specified  keysym. 

A  modifier_list/keysym  combination  in  a  translation  matches  a  modifiers/keycode 
combination  in  an  event  in  the  following  cases: 
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•  If  a  colon  (:)  is  used,  the  Intrinsics  call  the  display's  xtKeyProc  with  the  keycode  and 
modifiers.  In  order  to  match,  the  value  of 

(modifiers    &    ' modif iers_return) 
must  equal  modif  ier_list,  and  keysym_return  must  equal  the  given  keysym. 

•  If  (:)  is  not  used,  the  Intrinsics  mask  off  all  "don't  care"  bits  from  the  modifiers.  This 
value  must  be  equal  to  modif  ier_list.  Then,  for  each  possible  combination  of 
"don't  care"  modifiers  in  the  modif  ier_list,  the  Intrinsics  call  the  display's  Xt 
KeyProc  with  the  keycode  and  that  combination  ORed  with  the  cared-about  modifier 
bits  from  the  event  keysym_return  must  match  the  keysym  in  the  translation. 

Event  Types 

The  Event  Type  field  describes  XEvent  types.  In  addition  to  the  standard  Xlib  symbolic 
event  type  names,  the  following  event  type  synonyms  are  defined: 

Table  F-2.  EventType  Values 


Type 

Meaning 

Key  Or  KeyDown 

KeyPress 

KeyUp 

KeyRelease 

BtnDown 

ButtonPress 

BtnUp 

ButtonRe  lease 

Motion,  PtrMoved, 

MotionNotify 

or  MouseMoved 

Enter  or  EnterWindow 

EnterNotify 

Leave  or  LeaveWindow 

LeaveNotify 

Focusln 

Focusln 

FocusOut 

FocusOut 

Keymap 

KeymapNotify 

Expose 

Expose 

GrExp 

GraphicsExpose 

NoExp 

NoExpose 

Visible 

VisibilityNotify 

Create 

CreateNotify 

Destroy 

DestroyNotify 

Unmap 

UnmapNotify 

Map 

MapNotify 

MapReq 

MapRequest 

Reparent 

ReparentNotify 

Configure 

Conf  igureNotify 

Conf  igureReq 

Conf  igureRequest 

Grav 

GravityNotify 

ResReq 

ResizeRequest 

Circ 

CirculateNotify 

CircReq 

CirculateRequest 
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Table  F-2.  EventType  Values  (continued) 


Type 

Meaning 

Prop 

PropertyNotify 

SelClr 

Select  ionClear 

SelReq 

Select  ionRequest 

Select 

Select  ionNot  if  y 

Clrmap 

ColormapNotify 

Message 

ClientMessage 

Mapping 

MappingNotify 

The  supported  abbreviations  are  listed  in  Table  F-3. 
Table  F-3.  Modifier  Key  Abbreviations 


Abbreviation 


Ctrl 

Meta 

Shift 

BtnlDown 

BtnlUp 

Btn2Down 

Btn2Up 

BtnSDown 

Btn3Up 

Btn4Down 

Btn4Up 

BtnSDown 

BtnSUp 

BtnMotion 

BtnlMotion 

Btn2Motion 

BtnSMotion 

Btn4Motion 

Btn5Motion 


Meaning 


KeyPress  with  control  modifier 
Keypress  with  meta  modifier 
KeyPress  with  shift  modifier 
ButtonPress  with  Btnl  detail 
ButtonRelease  with  Btnl  detail 
ButtonPress  with  Btn2  detail 
ButtonRelease  with  Btn2  detail 
ButtonPress  with  Btn3  detail 
ButtonRelease  with  Btn3  detail 
ButtonPress  with  Btn4  detail 
ButtonRelease  with  Btn4  detail 
ButtonPress  with  Btn5  detail 
ButtonRelease  with  Btn5  detail 
Mot  ionNot  if  y  with  any  button  modifier 
Mot  ionNot  if  y  with  Buttonl  modifier 
Mot  ionNot  if  y  with  Button2  modifier 
Mot  ionNot  if  y  with  ButtonS  modifier 
Mot  ionNot  if  y  with  Button4  modifier 
Mot  ionNot  if  y  with  ButtonS  modifier 


The  detail  field  is  event-specific  and  normally  corresponds  to  the  detail  field  of  the 
corresponding  event  as  described  by  the  X  Protocol  specification.  The  detail  field  is  sup 
ported  for  the  following  event  types: 


Appendix  F:  Translation  Table  Syntax 


715 


Table  F-4.  Event  Types  That  Support  a  detail  Field 


Event 


Event  Field 


KeyPress 

KeyRelease 

ButtonPress 

ButtonRelease 

MotionNotify 

EnterNotify 

LeaveNotify 

Focusln 

FocusOut 

PropertyNotify 

Select ionClear 

Select ionRequest 

Select ionNot if y 

ClientMessage 

MappingNotify 


Keysym  from  event  detail  (keycode) 

Keysym  from  event  detail  (keycode) 

Button  from  event  detail 

Button  from  event  detail 

Event  detail 

Event  mode  (not  detail) 

Event  mode  (not  detail) 

Event  mode  (not  detail) 

Event  mode  (not  detail) 

Atom 

Selection 

Selection 

Selection 

Type 

Request 


If  the  event  type  is  KeyPress  or  KeyRelease,  the  detail  field  specifies  a  keysym 
name  in  standard  format  that  is  matched  against  the  event  as  described  above;  for  example, 
<Key>A. 

For  the  events  PropertyNotify,  SelectionClear,  SelectionRequest, 
SelectionNotify,  and  ClientMessage,  the  detail  field  is  specified  as  an  atom 
name;  for  example,  <Message>WM_PROTOCOLS.  For  the  events  MotionNotify, 
EnterNotify,  LeaveNotify,  Focusln,  FocusOut,  and  MappingNotify,  either 
the  symbolic  constants  as  defined  by  the  X  Protocol  specification  or  the  numeric  values  may 
be  specified. 

If  no  detail  field  is  specified,  then  any  value  in  the  event  detail  is  accepted  as  a  match. 

A  keysym  can  be  specified  as  any  of  the  standard  keysym  names,  a  hexadecimal  number  pre 
fixed  with  Ox  or  OX,  an  octal  number  prefixed  with  0,  or  a  decimal  number.  A  keysym 
expressed  as  a  single  digit  is  interpreted  as  the  corresponding  Latin  1  keysym.  For  example, 
0  is  the  keysym  XK_0.  Other  single  character  keysyms  are  treated  as  literal  constants  from 
Latin  1,  for  example,  /  is  treated  as  0x21.  Standard  keysym  names  are  as  defined  in 
<Xlllkeysymdef.h>  with  the  XK_  prefix  removed.  (See  Appendix  H,  Keysyms,  in  Volume 
Two,  Xlib  Reference  Manual.) 
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Canonical  Representation 


Every  translation  table  has  a  unique,  canonical  text  representation.  This  representation  is 
passed  to  a  widget's  display_accelerator  method  to  describe  the  accelerators 
installed  on  that  widget.  The  table  below  shows  the  canonical  representation  of  a  translation 
table  file.  (See  also  the  section  on  "Syntax"  earlier  in  this  appendix.) 

translationTable  =  {  production  } 

production  =  Ihs  ":"  rhs  "\n" 

Ihs  =  event  { ","  event  } 

event  =  [modifierjist]  "<"event_type">"  [ "("  count["+"]  ")"  ]  {detail} 

modifierjist  =  ["!"]  [":"]  {modifier} 

modifier  =  ["""']  modifier_name 

count  =  ("1"  I  "2"  I  "3"  I  "4"  I   ...) 

modifier_name  =  "@"  <keysym>  I  <see  canonical  modifier  names  below> 

event_type  =  <see  canonical  event  types  below> 

detail  =  <event  specific  details> 

rhs  =  {  name "("  [params] ")" } 

name  =  namechar  {  namechar  } 

namechar  =  { "a"-"z"  I  "A"-"Z"  I  "0"-"9"  I  "_"  I  "-"  } 

params  =  string  {","  string}. 

string  =  quoted_string 

quoted_string  =  """  {<Latin  1  character>}  """ 


The  canonical  modifier  names  are: 


Buttonl 
Button2 
Button3 
Button^ 
Buttons 


Modi 
Mod2 
Mod3 
Mod4 
Mod5 


The  canonical  event  types  are: 


ButtonPress 

ButtonRelease 

CirculateNotify 

CirculateRequest 

ClientMessage 

ColormapNotify 

ConfigureNotify 

Conf igureRequest 

CreateNotify 


DestroyNotify 

EnterNotify 

Expose 

Focusln 

FocusOut 

GraphicsExpose 

GravityNotify 

KeymapNotify 


Ctrl 

Shift 

Lock 


KeyPress 

KeyRelease 

LeaveNotify 

MapNotify 

MappingNotify 

MapRequest 

MotionNotify 

NoExpose 


PropertyNotif y 

Repar en t Notify 

ResizeRequest 

SelectionClear 

SelectionNotify 

SelectionRequest 

UnmapNotify 

VisibilityNotify 
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Examples 

•  Always  put  more  specific  events  in  the  table  before  more  general  ones: 

Shift  <BtnlDown>  :  twas()\n\ 
<BtnlDown>  :  brilligO 

•  For  double-click  on  Button  1  Up  with  Shift,  use  this  specification: 

Shift<BtnlUp>(2)     :    and() 
This  is  equivalent  to  the  following  line  with  appropriate  timers  set  between  events: 

Shift <BtnlDown>, Shift <BtnlUp>, Shift <BtnlDown>, Shift<BtnlUp>  :  and () 

•  For  double-click  on  Button  1  Down  with  Shift,  use  this  specification: 

Shift<BtnlDown>(2)  :  the() 

This  is  equivalent  to  the  following  line  with  appropriate  timers  set  between  events: 
Shift<BtnlDown>,Shift<BtnlUp>,Shift<BtnlDown>    :    the() 

•  Mouse  motion  is  always  discarded  when  it  occurs  between  events  in  a  table  where  no 
motion  event  is  specified: 

<BtnlDown>, <BtnlUp>  :  slithyO 

This  is  taken,  even  if  the  pointer  moves  a  bit  between  the  down  and  up  events.  Similarly, 
any  motion  event  specified  in  a  translation  matches  any  number  of  motion  events.  If  the 
motion  event  causes  an  action  procedure  to  be  invoked,  the  procedure  is  invoked  after 
each  motion  event 

•  If  an  event  sequence  consists  of  a  sequence  of  events  that  is  also  a  non-initial  subse 
quence  of  another  translation,  it  is  not  taken  if  it  occurs  in  the  context  of  'the  longer 
sequence.  This  occurs  mostly  in  sequences  like  the  following: 

<BtnlDown>, <BtnlUp>  :  toves()\n\ 
<BtnlUp>  :   did() 

The  second  translation  is  taken  only  if  the  button  release  is  not  preceded  by  a  button  press 
or  if  there  are  intervening  events  between  the  press  and  the  release.  Be  particularly 
aware  of  this  when  using  the  repeat  notation,  above,  with  buttons  and  keys  because  their 
expansion  includes  additional  events,  and  when  specifying  motion  events  because  they 
are  implicitly  included  between  any  two  other  events.  In  particular,  pointer  motion  and 
double-click  translations  cannot  coexist  in  the  same  translation  table. 

•  For  single  click  on  Button  1  Up  with  Shift  and  Meta,  use  this  specification: 

Shift  Meta  <BtnlDown>f  Shift  Meta<BtnlUp>:  gyre() 

•  For  multiple  clicks  greater  than  or  equal  to  a  minimum  number  n,  a  plus  sign  (+)  may  be 
appended  to  the  final  (right-most)  count  in  an  event  sequence.   The  actions  will  be 
invoked  on  the  nth  click  and  on  each  subsequent  click  arriving  within  the  multi-click 
time  interval.  For  example: 
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Shift  <BtnlUp>(2+)  :  and ( ) 

•  To  indicate  EnterNotif  y  with  any  modifiers,  use  this  specification: 

<Enter>    :    gimble() 

•  To  indicate  EnterNotif  y  with  no  modifiers,  use  this  specification: 

None  <Enter>  :  in() 

•  To  indicate  EnterNotify  with  Button  1  Down  and  Button  2  Up  and  "don't  care" 
about  the  other  modifiers,  use  this  specification: 

Buttonl  ~Button2  <Enter>  :  the() 

•  To  indicate  EnterNotify  with  Buttonl  Down  and  Button2  Down  exclusively,  use  this 
specification: 

!    Buttonl   Button2    <Enter>    :    wabe ( ) 
You  do  not  need  to  use  a  tilde  (")  with  an  exclamation  point  (!). 
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StringDefs.h  Header  File 


This  appendix  lists  the  contents  of  the  StringDefs.h  header  file.  The  contents  are  classified 
by  resource  names,  class  types,  representation  types,  and  constants. 


Table  G-1.  Resource  Names 


Resource  Name 


XtNaccelerators 

XtNallowHoriz 

XtNallowVert 

XtNancest or Sensitive 

XtNbackground 

XtNbackgroundP ixmap 

XtNbitmap 

XtNborderColor 

XtNborder 

XtNborderP  ixmap 

XtNborderWidth 

XtNcallback 

XtNchildren 

XtNcolormap 

XtNdepth 

XtNdestroyCallback 

XtNeditType 

XtNfile 

XtNfont 

XtNforceBars 

XtN foreground 

XtNfunction 

XtNheight 

XtNhighlight 

XtNhSpace 

XtNindex 

XtNinitialResourcesPersistent 
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Value 


"accelerators" 

"allowHoriz" 

"allowVert" 

"ancestorSensitive" 

"background" 

"background?  ixmap" 

"bitmap" 

"borderColor" 

"borderColor" 

"border? ixmap" 

"borderWidth" 

"callback" 

"children" 

"colormap" 

"depth" 

"destroyCallback" 

"editType" 

"file" 

"font" 

"forceBars" 

"foreground" 

"function" 

"height" 

"highlight" 

"hSpace" 

"index" 

"initialResourcesPersistent ' 
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Table  G-1.  Resource  Names  (continued) 


Resource  Name 


Value 


XtNinnerHeight 

XtNinnerWidth 

XtNinnerWindow 

XtNinsert Posit ion 

XtNinternalHeight 

XtNinternalWidth 

XtNjumpProc 

XtNjustify 

XtNknobHeight 

XtNknoblndent 

XtNknobPixel 

XtNknobWidth 

XtNlabel 

XtNlength 

XtNlowerRight 

XtNmappedWhenManaged 

XtNmenuEntry 

XtNname 

XtNnotify 

XtNnumChildren 

XtNorientation 

XtNparameter 

XtNpixmap 

XtNpopupCallback 

XtNpopdownCallback 

XtNresize 

XtNreverseVideo 

XtNscreen 

XtNscrollProc 

XtNscrollDCursor 

XtNscrollHCursor 

XtNscrollLCursor 

XtNscrollRCursor 

XtNscrollUCursor 

XtNscrollVCursor 

XtNselection 

XtNse lection Array 

XtNsensitive 

XtNshown 

XtNspace 

XtNstring 

XtNtextOptions 

XtNtextSink 

XtNtextSource 


"innerHeight" 

"innerWidth" 

"innerWindow" 

"insert Posit ion" 

"internalHeight" 

"internalWidth" 

" jumpProc" 

"justify" 

"knobHeight" 

"knoblndent" 

"knobPixel" 

"knobWidth" 

"label" 

"length" 

"lowerRight" 

"mappedWhenManaged1 

"menuEntry" 

"name" 

"notify" 

"numChildren" 

"orientation" 

"parameter" 

"pixmap" 

"popupCallback" 

"popdownCallback" 

"resize" 

"reverseVideo" 

"screen" 

"scrollProc" 

"scrollDCursor" 

"scrollHCursor" 

"scrollLCursor" 

"scrollRCursor" 

"scrollUCursor" 

"scrollVCursor" 

"selection" 

"selectionArray" 

"sensitive" 

"shown" 

"space" 

"string" 

"textOptions" 

"textSink" 

"textSource" 
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Table  G-1.  Resource  Names  (continued) 


Resource  Name 


Value 


XtNthickness 

XtNthumb 

XtNthumbProc 

XtNtop 

XtNtranslations 

XtNunrealizeCallback 

XtNupdate 

XtNuseBottom 

XtNuseRight 

XtNvalue 

XtNvSpace 

XtNwidth 

XtNwindow 

XtNx 

XtNy 


"thickness" 

"thumb" 

"thumbProc" 

"top" 

"translations" 

"unreal izeCallback1 

"update" 

"useBottom" 

"useRight" 

"value" 

"vSpace" 

"width" 

"window" 

"x" 


Table  G-2.  Class  Types 


Class  Type 

Value 

XtCAccelerators 

"Accelerators" 

XtCBackground 

"Background" 

XtCBitmap 

"Bitmap" 

XtCBoolean 

"Boolean" 

XtCBorderColor 

"BorderColor" 

XtCBorderWidth 

"BorderWidth" 

XtCCallback 

"Callback" 

XtCColormap 

"Colormap" 

XtCColor 

"Color" 

XtCCursor 

"Cursor" 

XtCDepth 

"Depth" 

XtCEditType 

"EditType" 

XtCEventBindings 

"EventBindings" 

XtCFile 

"File" 

XtCFont 

"Font" 

XtCForeground 

"Foreground" 

XtCFraction 

"Fraction" 

XtCFunction 

"Function" 

XtCHeight 

"Height" 

XtCHSpace 

"HSpace" 
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Table  G-2.  Class  Types  (continued) 


Class  Type 


Value 


XtCIndex 

XtCInitialResourcesPersistent 

XtCInsertPosition 

XtCInterval 

XtCJustify 

XtCKnoblndent 

XtCKnobPixel 

XtCLabel 

XtCLength 

XtCMappedWhenManaged 

XtCMargin 

XtCMenuEntry 

XtCNotify 

XtCOrientation 

XtCParameter 

XtCPixmap 

XtCPosition 

XtCReadOnly 

XtCResize 

XtCReverseVideo 

XtCScreen 

XtCScrollProc 

XtCScrollDCursor 

XtCScrollHCursor 

XtCScrollLCursor 

XtCScrollRCursor 

XtCScrollUCursor 

XtCScrollVCursor 

XtCSelection 

XtCSensitive 

XtCSelectionArray 

XtCSpace 

XtCString 

XtCTextOptions 

XtCTextPosition 

XtCTextSink 

XtCTextSource 

XtCThickness 

XtCThumb 

XtCTranslations 

XtCValue 

XtCVSpace 

XtCWidth 

XtCWindow 


"Index" 

"InitialResourcesPersistent" 

"InsertPosition" 

"Interval" 

"Justify" 

"Knoblndent" 

"KnobPixel" 

"Label" 

"Length" 

"MappedWhenManaged" 

"Margin" 

"MenuEntry" 

"Notify" 

"Orientation" 

"Parameter" 

"Pixmap" 

"Position" 

"Readonly" 

"Resize" 

"ReverseVideo" 

"Screen" 

"ScrollProc" 

"ScrollDCursor" 

"ScrollHCursor" 

"ScrollLCursor" 

"ScrollRCursor" 

"ScrollUCursor" 

"ScrollVCursor" 

"Selection" 

"Sensitive" 

" Select ionArray" 

"Space" 

"String" 

"TextOptions" 

"TextPosition" 

"TextSink" 

"TextSource" 

"Thickness" 

"Thumb" 

"Translations" 

"Value" 

"VSpace" 

"Width" 

"Window" 
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Table  G-2.  Class  Types  (continued) 
Class  Type 


Value 


xtcx 

XtCY 


Table  G-3.  Representation  Types 
Representation  Type  Value 


XtRAcceleratorTable 

XtRAtom 

XtRBitmap 

XtRBool 

XtRBoolean 

XtRCallback 

XtRCallProc 

XtRCardinal 

XtRColor 

XtRColormap 

XtRCursor 

XtRDimension 

XtRDisplay 

XtREditMode 

XtREnum 

XtRFile 

XtRFloat 

XtRFont 

XtRFontStruct 

XtRFunction 

XtRGeometry 

XtR Immediate 

XtRInitialState 

XtRInt 

XtRJustify 

XtRLongBoolean 

XtRObject 

XtROrientation 

XtRPixel 

XtRPixmap 

XtRPointer 

XtRPosition 

XtRScreen 

XtRShort 

XtRString 


"AcceleratorTable1 

"Atom" 

"Bitmap" 

"Bool" 

"Boolean" 

"Callback" 

"CallProc" 

"Cardinal" 

"Color" 

"Colormap" 

"Cursor" 

"Dimension" 

"Display" 

"EditMode" 

"Enum" 

"File" 

"Float" 

"Font" 

"FontStruct" 

"Function" 

"Geometry" 

"Immediate" 

"InitialState" 

"Int" 

"Justify" 

XtRBool 

"Object" 

"Orientation" 

"Pixel" 

"Pixmap" 

"Pointer" 

"Position" 

"Screen" 

"Short" 

"String" 
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Table  G-3.  Representation  Types  (continued) 


Representation  Type 


Value 


XtRStringArray 

XtRStringTable 

XtRUnsignedChar 

XtRTranslationTable 

XtRVisual 

XtRWidget 

XtRWidgetClass 

XtRWidgetList 

XtRWindow 


"StringArray" 

"StringTable" 

"UnsignedChar" 

"TranslationTable" 

"Visual" 

"Widget" 

"WidgetClass" 

"WidgetList" 

"Window" 


Table  G-4.  Constants 


Constant 


Value 


Boolean  Enumeration: 

XtEoff 

XtEfalse 

XtEno 

XtEon 

XtEtrue 

XtEyes 

Orientation  Enumeration: 

XtEvertical 
XtEhorizontal 

Text  Edit  Enumeration: 

XtEtextRead 

XtEtextAppend 

XtEtextEdit 

Color  Enumeration: 

XtExtdefaultbackground 
Xt Ext default foreground 

Font 

XtExtdefaultfont 


"off" 

"false" 

"no" 

"on" 

"true" 

"  ye  s  " 

"vertical" 
"horizontal" 

"read" 

"append" 

"edit" 

"xtdefaultbackground" 
"xt default foreground" 

"xtdefaultfont" 
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H 

Release  Notes 


The  interfaces  described  by  this  specification*  have  undergone  several  sets  of  revisions  in 
the  course  of  adoption  as  an  X  Consortium  standard  specification.  Having  now  been  adopted 
by  the  Consortium  as  a  standard  part  of  the  X  Window  System,  it  is  expected  that  this  and 
future  revisions  will  retain  backward  compatibility.  This  means  that  fully  conforming  imple 
mentations  of  these  specifications  may  be  produced.  These  implementations  will  provide 
source  compatibility  with  widgets  and  applications  written  to  previous  Consortium  standard 
revisions. 

The  Intrinsics  do  not  require  widget  programmers  to  retain  source  or  binary  compatibility  for 
their  widgets  as  they  evolve,  but  several  conventions  have  been  established  to  assist  those 
developers  who  want  to  provide  such  compatibility. 

In  particular,  widget  programmers  may  wish  to  conform  to  the  convention  described  in  Intro- 
duction(3)  when  defining  class  extension  records. 


hi.1   Determining  Specification  Revision  Level 

Widget  and  application  developers  who  wish  to  maintain  a  common  source  pool  that  will 
build  properly  with  implementations  of  the  Intrinsics  at  different  revision  levels  of  these 
specifications  may  use  the  symbolic  macro  xtSpecif  icationRelease. 

fdefine  XtSpecif icationRelease  4 

Since  the  symbol  XtSpecif  icationRelease  is  new  to  Release  4,  widgets  and  applica 
tions  desiring  to  build  against  earlier  implementations  should  test  for  the  presence  of  this 
symbol  and  assume  only  Release  3  interfaces  if  the  definition  is  not  present 


*This  appendix  is  adapted  from  the  Xt  specification  chapter  entitled,  "Evolution  of  the  Intrinsics. 
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H.2  Release  3  to  Release  4  Compatibility 

At  the  data  structure  level,  Release  4  retains  binary  compatibility  with  Release  3  (the  first  X 
Consortium  standard  release)  for  all  data  structures  except  WMShellPart,  TopLevel- 
ShellPart  and  TransientShellPart.  Release  4  changed  the  argument  type  to  most 
procedures  that  now  take  arguments  of  type  XtPointer  and  structure  members  that  are 
now  of  type  XtPointer  in  order  to  avoid  potential  problems  with  conformity  to  ANSI  C. 
Most  implementations  are  expected  to  be  binary-compatible  with  the  previous  definition. 

Two  fields  in  CoreClassPart  were  changed  from  Boolean  to  xtEnum  to  give  imple 
mentations  additional  freedom  in  specifying  the  representations  of  each.  This  change  should 
require  no  source  modification. 

H.2.1    Additional  Arguments 

Arguments  were  added  to  the  procedure  definitions  for  XtlnitProc,  xtSetValues- 
Func  and  xt  Event  Handler  to  provide  more  information  and  to  allow  event  handlers  to 
abort  further  dispatching  of  the  current  event  (caution  is  advised!).  The  added  arguments  to 
XtlnitProc  and  XtSetValuesFunc  make  the  initialize_hook  and 
set_values_hook  methods  obsolete,  but  the  hooks  have  been  retained  for  those  widgets 
that  used  them  in  Release  3. 


H.2. 2   set  values  almost  Methods 

The  use  of  the  arguments  by  a  set_values_almost  method  was  poorly  described  in 
Release  3  and  was  inconsistent  with  other  conventions. 

The  current  specification  for  the  manner  in  which  a  set_values_almost  method 
returns  information  to  the  Intrinsics  is  not  compatible  with  the  Release  3  specification,  and 
all  widget  implementations  should  verify  that  any  set_values_almost  methods  con 
form  to  the  current  interface. 

No  known  implementation  of  the  Intrinsics  correctly  implemented  the  Release  3  interface,  so 
the  impact  of  this  specification  change  is  expected  to  be  small. 

H.2. 3   Query  Geometry 

A  Composite  widget  layout  routine  that  calls  xtQueryGeometry  is  now  expected  to  store 
the  complete  new  geometry  in  the  intended  structure;  previously,  the  specification  said 
"store  the  changes  it  intends  to  make."  Only  by  storing  the  complete  geometry  does  the 
child  have  any  way  to  know  what  other  parts  of  the  geometry  may  still  be  flexible.  Existing 
widgets  should  not  be  affected  by  this,  except  to  take  advantage  of  the  new  information. 
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H.2.4   unrealizeCallback  Callback  List 

To  provide  a  mechanism  for  notifying  widgets  when  they  become  unrealized  through  a  call  to 
xt Unreal! zewidget,  the  callback  list  name  unrealizeCallback  has  been  defined 
by  the  Intrinsics.  A  widget  class  that  requires  notification  on  unrealize  may  declare  a  call 
back  list  resource  by  this  name.  No  class  is  required  to  declare  this  resource,  but  any  class 
that  did  so  in  a  prior  revision  may  find  it  necessary  to  modify  the  resource  name  if  it  does  not 
wish  the  new  semantics. 


H.2.5   Subclasses  of  WMShell 

The  formal  adoption  of  the  Inter-Client  Communication  Conventions  Manual  as  an  X  Con 
sortium  standard  has  meant  the  addition  of  four  fields  to  WMShellPart  and  one  field  to 
TopLevelShellPart.  In  deference  to  some  widget  libraries  that  had  developed  their 
own  additional  conventions  to  provide  binary  compatibility,  these  five  new  fields  were  added 
at  the  end  of  the  respective  data  structures. 

To  provide  more  convenience  for  TransientShells,  a  field  was  added  to  the  previously  empty 
TransientShellPart.  On  some  architectures  the  size  of  the  part  structure  will  not 
have  changed  as  a  result  of  this. 

Any  widgets  that  are  subclasses  of  TopLevelShell  or  TransientShell  must  at  minimum  recom 
pile  with  the  new  data  structure  declarations.  Because  WMShellPart  no  longer  contains  a 
contiguous  xsizeHints  data  structure,  a  subclass  that  expected  to  do  a  single  structure 
assignment  of  an  XSizeHints  structure  to  the  size_hints  field  of  WMShellPart 
must  be  revised,  though  the  old  fields  remain  at  the  same  positions  within  WMShellPart. 

H.2.6   Resource  Type  Converters 

A  new  interface  declaration  for  resource  type  converters  was  defined  to  provide  more  infor 
mation  to  converters,  to  support  conversion  cache  cleanup  with  resource  reference  counting, 
and  to  allow  additional  procedures  to  be  declared  to  free  resources.  The  old  interfaces 
remain  and  a  new  set  of  procedures  was  defined  that  work  only  with  the  new  type  converter 
interface. 

In  the  now  obsolete  old  type  converter  interface,  converters  are  reminded  that  they  must 
return  the  size  of  the  converted  value  as  well  as  its  address.  The  example  indicated  this  but 
the  description  of  xt Converter  was  incomplete. 
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H.2.7   Keysym  Case  Conversion  Procedure 

The  specification  for  the  xtCaseProc  prototype  procedure  has  been  changed  to  match  the 
Release  3  implementation,  which  included  necessary  additional  information  required  by  the 
function  (a  pointer  to  the  display  connection)  and  corrects  the  argument  type  of  the  source 
KeySym  argument  No  known  implementation  of  the  Intrinsics  implemented  the  previously 
documented  interface. 


H.2.8   Non-widget  Objects 

Formal  support  for  non- widget  objects  is  new  to  Release  4.  A  prototype  implementation  was 
latent  in  at  least  one  Release  3  implementation  of  the  Intrinsics,  but  the  specification  has 
changed  somewhat.  The  most  significant  change  is  the  requirement  for  a  Composite  widget 
to  declare  the  CompositeClassExtension  record  with  the  accepts_objects 
field  set  to  True  in  order  to  permit  a  client  to  create  a  non- widget  child. 

The  addition  of  this  extension  field  insures  that  Composite  widgets  written  under  Release  3 
will  not  encounter  unexpected  errors  if  an  application  attempts  to  create  a  non-widget  child. 
In  Release  4  there  is  no  requirement  that  all  Composite  widgets  implement  the  extra  func 
tionality  required  to  manage  windowless  children,  so  the  accept_objects  field  also 
allows  a  Composite  widget  to  declare  that  it  is  never  prepared  to  do  so. 
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Master  Index 


The  Master  Index  combines  Volumes  Four  and  Five  index  entries,  making  it 
easy  to  look  up  the  appropriate  references  to  a  topic  in  either  volume.  PM 
refers  to  the  X  Toolkit  Intrinsics  Programming  Manual.  RM  refers  to  the  X 
Toolkit  Intrinsics  Reference  Manual. 


Index 


!    (see  modifiers) 

#  directive    (see  translations) 


accelerators   about,  PM:59, 152, 

193,211-217,265,531 
adding,  PM:212 
and  translations;  conflicts  with, 

PM:215; 
translation  table  limitations, 

PM:213 
compiling  accelerator  table, 

RM:274 
defining  default  table  in  code, 

PM:216 

event  propagation,  PM:213 
for  gadgets,  PM:383 
for  menus,  PM:379, 383 
installing,  PM:211;  RM:242-244; 

in  multiple  widgets,  PM:215 
not  usable  in  gadgets,  PM:386 
(see  also  methods,  display_accel- 
erator;  XtlnstallAccelerators.) 
accept_focus  method   PM:404; 

RM:387, 473 

accepts_objects  field   PM:394 
access  control  list  PM:531 
action  hooks   PM:408 
actions   PM:47, 49, 365, 369, 394, 

411 
about,  PM:29, 32, 41-42, 531; 

RM:637 

action  proc  format,  PM:48 
actions  table;  about,  PM:53 1 ; 
XtActionProc,  RM:374-375 
adding  to  widget,  PM:46 
arguments  to,  PM:114 


contrasted  with  callbacks, 

PM:49, 114 

defined  in  widget  implementa 
tion  file,  PM:148-149 
gadget  parent  example, 

PM:393-394 
in  gadgets,  PM:386 
naming  conventions,  PM:45 
passing  arguments  to,  PM:114 
registering  with  Translation  Man 
ager,  RM:63-64 
using  event  data,  PM:229 
widget  instance  pointer,  PM:190 
widget/application  conflicts, 

PM.-148 

(see  also  XtAddActions;  XtAp- 
pAddActions;  XtMenuPop- 
down;  XtMenuPopup.) 
actions  table    adding,  PM:46-47; 

RM:63-64,  81-82 
declaring/registering  with 

Resource  Manager,  RM:81-82 
example,  PM:48 
format,  PM:48 
(see  also  actions.) 
active  grab   PM:364 
aliasing  font  names   PM:457 
AlmostProc    RM:439 
Alt  key   PM:202 

(see  also  modifiers.) 
ancestor   PM:532 
anonymous  ftp    PM:36 
application    applica- 

tionShellWidgetClass, 
RM:452-460 

application  contexts   PM:102 
about,  PM:102, 410^13, 532 
adding  display,  RM:188-189 
creating,  PM:1 02;  RM:  168 


Index 
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destroying  and  closing  displays, 

RM:180 

multiple,  PM:41 1-412 
XtOpenDisplay,  PM:413 
application  resources    about, 

PM:85 

data  structure,  PM:86 
retrieving  values,  PM:90 
application-defaults  file    about, 

PM:34, 38, 253 
directory,  PM:38 
naming  conventions,  PM:34,  38 
ApplicationShell   RM:429-430 
applicationShellWidgetClass 

PM:284 

appres  utility    PM:263 
ArgList   (see  argument  lists) 
arguments   Arg  structure,  PM:99 
argc,  PM:35, 96, 286 
ArgsProc,  RM:438 
ARGSUSED  lint  comment, 

PM:45 

argument  lists,  PM:57; 
about,  PM:99,  532; 
constructing/modifying  dynam 
ically,  RM:312-313; 
creating,  PM:57,  99-100; 
creating  dynamically,  PMrlOO; 
example,  PM:99-100; 
merging  ArgList,  RM:256; 
XtMergeArgLists,  RM:256 
argument  styles;  command  line, 

PM:95 

argv,  PM:35,  96, 286 
to  actions,  PM:114, 125 
varargs,  PM:97 
array    allocating,  RM:136 
elements,  determining  number, 

RM:263 

XtCalloc,  RM:136 
(see  also  XtNumber.) 
aspect  ratio    PM:288 
Athena  widgets   PM:19,38, 

69-70, 73, 75, 79, 278, 379 
about,  PM:  17, 532 
inheritance  among,  PM:19 
(see  also  Box  widget;  Command 
widget;  Dialog  widget;  Form 
widget;  Grip  widget;  Label 
widget;  MenuButton  widget; 
Paned  widget;  scrollbars, 
Scrollbar  widget;  Text 
widget.) 


atoms   about,  PM:303, 532 
obtaining;  example,  PM:306 
predefined,  PM:305 
standard,  PM:3 14 

augmenting  translations 
PM:50-51 


B 


background    about,  PM:58,  532 
background  processing, 

RM:419-420 
pixmap,  PM:58 
processing,  PM:239 
window  attribute,  PM:158 
background  option    (-back 
ground,  -bg),  PM:92-93 
backing  store    about,  PM:532 
backing_store  window  attribute 

PM:158-159 
about,  PM:269 

binding   tight  vs.  loose,  PM:252 
bit   bit  gravity  window  attribute, 

PM:158,532 
bit  plane,  PM:533 
bitmap    about,  PM:293, 533 

files,  PM:  106 
BitmapEdit  widget   PM:70, 

105-134,181,326 
about,  PM:  106, 497 
class  hierarchy  of,  PMil39 
instance  part  and  record,  PM:141 
BitmapEditClassRec 
PM:140-141,237 
BitmapEditRec   example, 

PM:141-142 
bitwise  OR    combining  mask 

symbols,  RM:7 1,120 
Boolean  values   PM:265 
border    about,  PM:533 
border  crossing  events, 

RM:666-671 
width,  PM:322 
border  option    (-border,  -bd), 

PM:93 
border  window  attribute 

PM:158 

bordercolor  option    (-border- 
color),  PM:93 
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borderwidth  option    (-bor- 
derwidth,  -bw),  PM:93 
bounding  box    PM:175;  RM:483 
Box  widget   PM:21,  65-75, 

212-217, 363-370 
example,  PM:65-67,  69-70 
BuIletinBoard  widget   PM:429 
ButtonPress  event   PM:201,366; 

RM:65 1-653 
ButtonRelease  event   PM:201, 

366;  RM:651-653 
buttons   PM:424 
grabbing,  PM:533 
mapping,  RM:689 
(see  also  command  buttons.) 
byte  order    PM:533 


caching   old  size,  PM:  1 83 
resource,  PM:271 
resource  conversion,  PM:271 
standard  atoms,  PM:314 
Xmu;  initializing,  PM:3 14 
callbacks   RM:376-377, 413 
about,  PM:28,  32,  41-42,  533; 

RM:638 

adding,  PM:43-44; 
more  than  one,  PM:84; 
to  callback  list,  RM:67-68; 
to  callback  resource,  RM:65-66 
arguments  to,  PM:45 
callback  list,  PM:84; 
deleting  method,  RM:296-297; 
determining  status,  RM:233; 
executive  methods,  RM:133; 
popping  down  widget, 

RM:128-129; 
popping  up  widget, 

RM:124-127; 
XtCallbackExclusive, 

RM:124-125; 

XtCallbackNone,  RM:126; 
XtCallbackNonexclusive, 

RM:127; 
XtCaUbackPopdown, 

RM:128-129; 
XtCallCallbacks,  RM:133; 
XtHasCallbacks,  RM:233; 
XtRemoveCallback,  RM:296; 
XtRemoveCallbacks,  RM:297 
contrasted  with  actions,  PM:49 


format,  PM:45 
naming  conventions,  PM:45 
passing  data,  PM:81-83 
pop-up  functions,  PM:84 
procedure,  RM:376-377 
XtAddCallback,  RM:65-66 
(see  also  XtCallbackProc; 
XtTimerCallbackProc.) 
Caption  widget   PM:429 
cascading  pop  ups    about, 
PM:357, 359, 374-379 
example,  PM:376-377 
case  converter   PM:205 
registering,  RM:290 
XtRegisterCaseConverter, 

RM:290 

chained  methods    (see  inheri 
tance) 
change_managed  method 

PM:322-324,  332;  RM:474 
in  constraint  widgets, 

PM:349-350 

CircuIateNotify  event   RM:654 
CircuIateRequest  event 

RM:654-655 
class    about,  PM:  18,  533 
class  name;  defined  in  Core 

class  part,  PM:  152 
class  part,  PM:  140; 
combining  into  class  record, 

PM:140; 

lack  of  new  fields,  PM:141 
class  record,  PM:  138; 
allocating  storage,  PM:142; 
BitmapEdit  widget, 

PM:140-141; 
contents,  PM:139 
class_initialize  method,  PM:156, 

270 

extension  stucture,  PM:414 
hierarchy,  PM:  138-139; 
AT&  T  Open  Look  widgets, 

PM:363; 

Athena  widgets,  PM:156,  363; 
gadgets,  PM:387-389; 
Motif,  PM:363; 
(see  also  widget  classes.) 
structure,  PM.-138-165; 

adding  resource  list  to,  PM:148 
classjnitializc  method    PM:156, 
270,  339, 394, 415;  RM:476 
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class_part_Initialize  method 

PM:156,339,342,394; 
RM:477 
client   about,  PM:6,  534 

client-server  model,  PM:6 
ClientMessage  event 

RM:656-657 

clipping  region   PM:534 
color   PM:58,  121,  159-160, 
265-266,  290 

determining  available,  PM:450 

displaying,  PM:450 

false,  PM:291 

hexadecimal  specification, 
PM:448 

names,  PM:447 

RGB  model,  PM:449 

specifying,  PM:447 
colorcell   PM:450 

about,  PM:534 

read-only,  PM:451 

read/write,  PM:451 

shared,  PM:451 

(see  also  colormap.) 
colormap    about,  PM:58,  450 

installing,  PM:290 

virtual,  PM:290 

window  attribute,  PM:159 

(see  also  events,  ColormapNo- 


colormap    about,  PM:534 
colormap  window  attribute 

PM:291 
CoIormapNotify  event 

RM:656-658 
command  buttons   PM:424,  426, 

436 
command  line   compUing,  PM:36 

options  (see  options) 
Command  widget   PM:19,  39, 
41^4,49,69,79,106,212, 
214-216,365-371,374,378, 
424-426,  436 
compiling  Xt   PM:36 
Composite   XtOrderProc  proto 

type  procedure,  RM:407 
composite  widgets   about,  PM:  16, 

321,  437,  534 

as  parent  and  child,  PM:332 
class,  PM:  16,  139; 
about,  PM:21,  65; 
XtNinsertPosition  resource, 
PM:335 


general  purpose,  PM:429, 440 
importance,  PM:428 
initial  size,  PM:325 
inserting  children,  PM:335 
management,  PM:322 
menus  and  control  areas,  PM:437 
reasons  for  writing,  PM:321 
resources,  PM:ix; 

(see  also  resources.) 
subclass;  XtlsComposite, 

RM:246 
using  within  other  widgets, 

PM:322 

(see  also  methods,  insert_child.) 
compound  widgets  PM:351-352 
compression  filters  (see  events, 

event  filters) 
ConfigureNotify  event 

RM:659-660 
ConfigureRequest  event 

RM:661-662 
connection   PM:535 
constants  (defined)   XtCacheAll, 

RM:638 

XtCacheByDisplay,  RM:638 
XtCacheNone,  RM:638 
XtCacheRefCount,  RM:638 
Constraint   destroy  method, 

RM:481 

initialize  method,  RM:496 
set_values  method,  RM:513-514 
constraint  widgets   PM:ix; 

RM:434-437, 434 
about,  PM:72, 321, 535; 

RM:434^37 
class,  PM:  139; 
about,  PM:23; 
part,  PM:340; 
refiguring  child  locations, 

PM:344-347 

management,  PM:336-351, 336 
part  structure,  PM:338 
resources,  PM:73-74, 338; 

RM:434-437; 
example,  PM:73-74 
writing,  PM:336 
XtlsConstraint,  RM:247 
(see  also  methods,  Constraint 
destroy;  methods,  set_values; 
resources.) 
consulting   PM:525 
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containment  PM:535 
conventions   action  function 

names,  PM:45 
application-defaults  file,  PM:34, 

38 

callback  function  names,  PM:45 
font  naming,  PM:453 
for  Xtlnherit  constants,  PM:158 
gadget  internals,  PM:388 
instance  variables  order,  PM:142 
keysym  naming,  PM:199 
public  function  names,  PM:1 16 
resource;  class,  PM:  147; 
names,  PM:147,  248; 
representation  types,  PM:147 
widget;  internals,  PM:138; 
source  file  names,  PM:138; 
structure  declarations,  PM:143, 

164-165 

conversion  caching   PM:271 

converters   PM:263-278, 41 1 

color  name  to  pixel  value, 

PM:  122, 265, 290 
Convert.h,  PM:273 
explicitly  invoking,  PM:274-275 
fontname  to  font,  PM:265 
function  pointer  to  callback  list, 

PM:270 

int  to  Boolean,  PM:266 
int  to  Dimension,  PM:266 
int  to  float,  PM:266 
int  to  font,  PM:266 
int  to  pixel,  PM:266 
int  to  pixmap,  PM:266 
int  to  Position,  PM:266 
int  to  short,  PM:266 
int  to  unsigned  char,  PM:266 
int  to  XColor,  PM:266 
Pixel  to  XColor,  PM:266 
registering,  RM:69,  83-85; 
case  converter,  PM:247; 

RM:290 

string  to  bitmap,  PM:269 
string  to  boolean,  PM:265 
string  to  cursor,  PM:265,  269 
string  to  Dimension,  PM:265 
string  to  Display,  PM:265 
string  to  file  descriptor,  PM:265 
string  to  float,  PM:265 
string  to  geometry,  PM:265 
string  to  initial  state,  PM:265 
string  to  int,  PM:265 
string  to  orientation  mode, 


PM:269 

string  to  Position,  PM:265 
string  to  short,  PM:265 
string  to  translation  table, 

PM:265 

string-to-justify  mode,  PM:269 
widget  name  to  widget  ID, 

PM:269 

XColor  to  Pixel,  PM:266 
(see  also  XtAppAddConverter; 

XtSetTypeConverter.) 
coordinate  system   PM:4,  535 
Core   PM:152 
class  part;  fields,  RM:484; 
initializing,  PM:151-153; 
initializing  example, 

PM:151-152 
class  structure;  in  gadgets, 

PM:388 
Core  widget  class,  PM:139; 

RM:438-442,  661-662; 
about,  PM:535 

CoreClassPart  structure,  PM:141 
CorePart  structure,  PM:141 
fields,  PM:  152; 
compress_enterleave,  PM:153, 

242; 
compress_exposure,  PM:153, 

176,242; 
compress_motion,  PM:153, 

242; 

display_accelerator,  PM:152; 
extension,  PM:153; 
superclass,  PM:152; 
tm_table,PM:153; 
version,  PM:  153; 
visiblejnterest,  PM:153, 237; 
widget_size,  PM:152; 
xrm_class,  PM:153; 
(see  also  methods,  set_val- 

ues_hook.) 
instance  record;  height  field, 

PM:325; 

width  field,  PM:325 
instance;  setting  size,  PM:  120 
methods,  RM:442 
widget  class,  PM:  17, 57; 
about,  PM:20; 
class  pointer,  PM:120; 
drawing  into  from  application, 

PM:1 19-120; 

hidden  superclasses,  PM:158; 
instance  default  size,  PM:120; 
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resources,  PM:57; 
superclasses,  PM:387; 
widgetClass  class  pointer, 

PM:120 

(see  also  methods;  methods, 
class_initialize;  methods, 
class_part_initialize;  methods, 
initialize.) 

Core  widget   PM:17, 118, 197 
drawing  into,  PM:1 19 
updating,  PM:122 
counter  incrementing   inside 

XtSetArg,  PM:55 
CreateNotify  event   RM:663-664 
Ctrl  key    PM:202 

(see  also  modifiers.) 
cursor    about,  PM:  159, 265, 535 

hotspot,  PM:539 
cursor  window  attribute 

PM:159 
cut  and  paste    (see  selections) 


D 


data    PM:546 
data  transfer  completion  method, 

RM:412 

datatypes,  RM:631 
(see  also  structures.) 
database    obtaining  for  display, 

RM:179 

(see  also  XtDatabase.) 
DECNet   PM:295 
decoration    PM:33,  293 
default  multiple  click  timing 

PM:207 

default  size    PM:184 
delete_child  method    PM:322; 

RM:478 

depth    PM:58, 173,  535 
descendants   PM:535 
destroy  method    PM:157, 169, 

187;RM:479 
about,  PM:187 
Constraint,  PM:340 
example  from  BitmapEdit, 

PM.-187 

DestroyNotify  event   RM:665 
destructors   PM:271 
details  in  translations    (see  trans 


lations) 

device    PM:536 
dialog  boxes   PM:384 
cascading,  PM:384 
grabs  in,  PM:384 
without  grabs,  PM:384 
Dialog  widget   PM:21, 75, 79, 

351-352 

popping  up,  PM:75 
DirectColor   PM:536 
directories   font,  PM:452 
display    about,  PM:6, 536 
adding;  XtOpenDisplay, 

RM:266-267 
closing,  RM:  139 
connecting  to  multiple  displays, 

PM:413 
depth,  PM:450 
display  Usts,  RM:483 
initializing,  RM:  188-1 89 
lists,  PM:  175 
XtCloseDisplay,  RM:139 
(see  also  XtDisplaylnitiaUze.) 
DISPLAY  environment  variable 

PM:58 

display  option    (-display),  PM:93 
display  pointer   returning  for 

widget,  RM:  187 
display_accelerator  method 

PM:216;  RM:482 
distributed  processing   PM:7 
DoesBackingStore  Xlib  macro 

PM:159 
DoesSaveUnders  Xlib  macro 

PM:159 

double  clicks   PM:46, 206-207 
downward  chaining   PM:154 
drawing    about,  PM:121, 142, 

153-155, 169, 175-178 
after  Expose  event,  PM:156 
bitmap  cells,  PM:  163 
coordinate  system,  PM:4 
due  to  set_values  method 

changes,  PM:  180 
in  expose  method,  PM:170 
into  Core  widget,  PM:1 19-120 
window  attributes,  PM:  158-159 
drop-down  menu    PM:359, 371 
example,  PM:373 
vs.  spring-loaded,  PM:360 
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E 


elements    (see  array) 
encapsulation    PM:31,536 
enter/leave  compression 

PM:242 
EnterNotify  event   PM:200-201, 

242, 365-366;  RM:666-671 
EnterWindow  event   PM:222 
environment  variables   DIS 
PLAY,  PM:58 
XAPPLRESDIR,  PM:253 
XENVIRONMENT,  PM:254 
error  database    obtaining, 

RM:96-98, 205-206 
error  handling   PM:96, 100, 

399-402 

and  application  contexts,  PM:402 
calling  fatal  error  handler, 

RM:193-195 

calling  fatal  error  handler  (high- 
level),  RM:93-94 
error  resource  database,  PM:401 ; 
obtaining,  RM:95; 
XtAppGetErrorDatabase, 

RM:95; 
XtAppGetErrorDatabaseText, 

RM:96-98; 

XtGetErrorDatabase,  RM:205; 
XtGetErrorDatabaseText, 

RM:206 
levels,  PM:400 
method,  RM:394 
procedure,  RM:395-396 
redefining  handlers,  PM:401 
string  conversion  warnings, 

PM:402 

XtAppError,  RM:92 
XtAppErrorMsg,  RM:93-94 
XtAppGetErrorDatabase,  RM:95 
XtAppGetErrorDatabaseText, 

RM:96-98 

XtAppSetErrorHandler,  RM:109 
XtAppSetERrorMsgHandler, 

RM:110 

XtError,RM:193 
XtErrorMsg,  RM:  194-195 
XtGetErrorDatabase,  RM:205 
XtGetErrorDatabaseText, 

RM:206 

XtSetErrorHandler,  RM:314 
XtSetErrorMsgHandler,  RM:315 


errors   error  procedure 

fatal  error  handler;  calling  (high- 
level),  RM:93-94, 194-195 

fatal  error  procedure;  calling 

(low-level),  RM:92; 
registering,  RM:109-110,  314 

listing,  RM:703 

nonfatal  error  procedure;  calling, 

RM:116; 
registering,  RM:  114-1 15, 329 

string  conversion  error  message, 
RM:333 

(see  also  XtAppError;  XtAppEr 
rorMsg;  XtAppSetEr 
rorHandler;  XtAppSetEr- 
rorMsgHandler; 
XtAppSetWar- 
ningMsgHandler;  XtError; 
XtErrorHandler;  XtErrorMsg; 
XtErrorMsgHandler;  XtSetEr- 
rorHand;  XtSetErrorMsg- 
Hand;  XtSetWar- 
ningMsgHandler. ) 
event  handlers   PM:32, 222-227 

about,  PM:30, 221, 536 

adding,  PM:222, 224-226; 
RM:398 

dispatching,  RM:186 

for  nonmaskable  events, 
PM:225-226 

procedure,  RM:397-398, 
400-401 

raw,  PM:227; 

registering  raw,  RM:76-77; 
removing  raw,  RM:302-303 

reasons  to  use,  PM:222 

registering,  RM:70-71 

removing,  RM:298-299 

XtAddEventHandler,  RM:70-71 

XtAddRawEventHandler, 
RM:76-77 

XtRemoveEventHandler, 
RM:298-299 

XtRemoveRawEventHandler, 
RM:302-303 

(see  also  XtDispatchEvent; 
XtEventHandler;  Xtln- 
putCallbackProc.) 
event  masks   about,  PM:222 

retrieving,  RM:  120- 121 

XtBuildEventMask,  RM:120-121 
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event  processing   RM:107 

XtAppProcessEvent,  RM:107 
events   about,  PM:  10, 195 
accessing  specific  data,  RM:649 
as  argument  of  action,  PM:49 
border  crossing,  RM:666-671 
ButtonPress,  PM:201, 366; 

RM:65 1-653 
ButtonRelease,  PM:201,  366; 

RM:65 1-653 

cancelling  source,  RM:301 
CirculateNotify,  RM:654 
CirculateRequest,  RM:654-655 
ClientMessage,  RM:656-657 
ColormapNotify,  RM:656-658 
ConfigureNotify,  RM:659-660 
ConfigureRequest,  RM:66 1-662 
CreateNotify,  RM:663-664 
DestroyNotify,  RM:663-665 
dispatching  handlers,  RM:186 
EnterNotify,  PM:200-201, 242, 

365-366 

EnterWindow,  PM:222 
event  compression,  PM:536 
event  data;  example  of  using  in 

an  action,  PM:228 
event  filters,  PM:153, 178,  242 
event  loop  (see  main  loop) 
event  masks;  about, 

PM:536-537;  RM:632 
event  members;  common, 

RM:650 

event  propagation,  PM:537 
event  queue,  PM:241 
event  sequences,  PM:210 
event  source,  PM:537 
event  structure,  PM:227 
event-driven  programming, 

PM:10-11 
event_mask  window  attribute, 

PM:159 
expose,  PM:10 
Expose,  PM:25, 116, 123, 125, 

153, 156, 237, 242, 366; 

RM:672-673 
Focusln,  PM:200, 222, 405, 537; 

RM:674-679 
FocusOut,  PM:200, 222, 405; 

RM:674-679 
frozen  event,  PM:538 
GraphicsExpose,  PM:197,  226; 

RM:680-681 
GravityNotify,  RM:682 


in  action  routines,  PM:125 

in  gadgets,  PM:386 

input  events;  XtRemovelnput, 

RM:301 

KeymapNotify,  RM:683 
KeyPress,  PM:201, 406; 

RM:684-686 

KeyRelease,PM:198,201 
LeaveNotify,  PM:200-201,  242, 

365-366;  RM:666-671 
list  of  types  and  structure  names, 

PM:229-230 
MapNotify,  RM:687-688 
MappingNotify,  RM:689-690 
MapRequest,  RM:691 
mocking  up  from  action, 

PM:175;  RM:483 
MotionNotify,  PM:201, 207, 222, 

242, 366;  RM:692-694 
next  event;  returning,  RM:262 
NoExpose,PM:197; 

RM:680-681 
nonmaskable,  PM:195, 213, 

224-226,541; 
example  of  handlers,  PM:195, 

213, 224 

processing,  RM:243 
processing  one  event;  XtPro- 

cessEvent,  RM:283 
propagation,  PM:213 
PropertyNotify,  RM:695 
ReparentNotify,  RM:696 
ResizeRequest,  RM:697 
returning  next  event,  RM:103 
selecting,  PM:213 
SelectionClear,  PM:294,  304; 

RM:698 
SelectionNotify,  PM:294, 305, 

310;  RM:699 
SelectionRequest,  PM:294, 296, 

305-306;  RM:700 
structures,  RM:650 
translation  table  abbreviations, 

PM:196-197 

using  inside  actions  or  event  han 
dlers,  PM:227-228;  RM:375 
VisibilityNotify,  PM:153, 197; 

RM:701-702 
XEvent;  example,  PM:228; 

RM:375; 
union,  RM:649 
XtAppNextEvent,  RM:103 
XtAppPending,  RM:106, 278 
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(see  also  exposure; 

XtDispatchEvent;  XtMain- 
Loop;  XtNextEvent.) 
expo.lcs.mit.edu   PM:36 
Expose  event   PM:366;  RM:72, 

672-673 
Expose  events   PM:25, 169, 178; 

RM:485 
expose  method   PM:  154, 169, 

175-178, 226;  RM:483-486 
about,  PM:  175 
example  from  BitmapEdit, 

PM:175 

in  gadgets,  PM:386, 391-392 
exposure    PM:10 
compression,  PM:176,  242; 

RM:484 
XtAddExposureToRegion, 

RM:72 

(see  also  events,  Expose.) 
extensions    about,  PM:  12, 537 
structures,  PM:394,  414 


directories,  PM:452 

display  (xfd),  PM:452 

families,  PM:452, 455 

fonts.dir  files,  PM:457 

naming  convention,  PM:453 

printer,  PM:452 

screen,  PM:452 

specifying,  PM:447 

specifying  as  resources,  PM:265 

using  file  name  as  alias,  PM:457 

wildcarding,  PM:454 
foreground   PM:537 
foreground  option    (-foreground, 

-fg),  PM:93 

Form  widget   PM:21, 106, 
336-351,440 

about,  PM:72-74, 73, 429, 440 

example,  PM:440 

layout  method,  PM:340 
freeing  storage  block   (see  stor 
age  block) 
ftp   PM:36 


fallback  resources   PM:257-258 
fatal  error   (see  XtError,  XtEr- 

rorMsg) 

fatal  error  handlers    (see  errors) 
file  events    (see  event  handlers) 
file  input   PM:230-233 
registering  file,  RM:75,  86-87 
source  masks,  PM:23 1 
XtAddlnput,  RM:75 
XtAppAddlnput,  RM:86-87 
files   filenames;  character  limit, 

PM:138 
using  names  in  resources, 

PM:265 

floating  point  numbers   PM:265 
Focusln  event  PM:200,222; 

RM:674-679 
FocusOut  event  PM:200, 222; 

RM:674-679 

font  conventions   bolding,  PM:vi 
itah'cs,  PM:vi 
typewriter  font,  PM:vi 
font  option   (-font),  PM:92-93 
fonts   about,  PM:537 
aliasing,  PM:456 
creating  databases  (mkfontdir), 
PM:458 


gadgets   RM:424 
about,  PM:  157, 357 
accelerators,  PM:383; 
not  usable,  PM:386 
actions  in,  PM:386 
class  hierarchy,  PM:387-388 
class  structure,  PM:389 
composite  parent,  PM:386, 

391-395 

Core  class  structure,  PM:388 
drawbacks  of,  PM:386 
event  handling  in,  PM:386 
expose  method,  PM:391 
implementation  file,  PM:390 
instance  structure,  PM:390 
internals,  PM:388-391 
private  header  file,  PM:389-390 
public  header  file,  PM:391 
query_geometry  method, 

PM:391 

reason  for,  PM:385 
set_values_almost  method, 

PM:391 

Sme,  PM.-379-391 
SmeBSB,  PM:379-391 
SmeLine,  PM:379-391 
superclass,  PM:390 
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unused  Core  fields  in, 

PM:390-391 
games    PM:234 
GCs    (see  graphics  contexts) 
geometry  management 

PM:69-70,287,322,335; 
RM:43 1-433 
about,  PM:35, 181, 183-186, 

321-352, 538;  RM:641 
border  width,  PM:322 
changes,  RM:244-246 
changing  (XtMakeGeometryRe- 
quest),  PM:325;  RM:244-246 
composite  resource,  PM:335 
compound  widgets,  PM:35 1-352 
constraint  class  part,  PM:340 
constraint  management,  PM:336 
delaying  recalculation,  PM:351 
height,  PM:325 
initial  geometry  negotiation, 

PM:324 

inserting  children,  PM:335 
minimal  useful  size,  PM:330 
querying,  RM:284-286; 
preferred  geometry, 

PM:332-333; 
XtQueryGeometry, 

RM:284-286 
resizing,  PM:321 
scope,  PM:322 
size  preferences,  PM:333 
stacking  order,  PM:322,  352 
trickle-down,  PM:333 
unmanaging  widget,  PM:332 
width,  PM:325 
(see  also  methods;  XtDes- 

troyWidget.) 
geometry  option   (-geometry), 

PM:93 
geometry_manager  method 

RM:487 

get_values_hook  method 
PM:157,216,279,479; 
RM:225, 49 1-492 
global  variables   PM:79,  82 
glyph   PM:538 
grabs   about,  PM:363, 53 1 , 538; 

RM:641 

active  vs.  passive,  PM:364 
adding  or  removing  explicitly, 

PM:385 

exclusive  vs.  nonexclusive, 
PM:364, 377 


global,  PM:364 

grab  modes,  PM:377 

in  dialog  boxes,  PM:384 

keyboard,  PM:363 

passive,  PM:364, 542 

pointer,  PM:363 

reasons  for  in  menus,  PM:365 

XtAddGrab,  RM:73-74 

XtRemoveGrab,  RM:300 
graphics   PM:121 

graphics  primitive,  PM:538 

(see  also  graphics  contexts.) 
graphics  contexts    about, 
PM:121, 142, 159,  538 

caching,  PM:  170, 173 

changing,  PM:173, 180 

creating,  PM:170, 172-174 

deallocating,  RM:293 

destroying,  RM:181 

exclusive  or  logical  function, 
PM:302 

freeing,  PM:180, 187;  RM:181 

hardcoding  values  in,  PM:174 

obtaining,  RM:207-208 

read-only,  PM:173 

reasons  for,  PM:121 

setting  with  resources,  PM:174 

(see  also  XtDestroyGC; 

XtGetGC;  XtReleaseGC.) 
GraphicsExpose  event   RM:72, 

680-681 

GraphicsExpose  events   PM:226 
gravity   PM:538 
GravityNotify  event   RM:650, 

682 

Grayscale    PM:538 
Grip  widget   PM:20,70 


H 

hardcoding   resources,  PM:40, 

97,99 

translations,  PM:51 
header  files   PM:32, 54, 59, 23 1 , 

387, 464 

not  included  twice,  PM:141 
private,  PM:543 
public,  PM:543 
height   PM:325 
checking  in  initialize  method, 
PM:170 
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hexadecimal  color  specification 

PM:448 

hints    about,  PM:284-294,  538; 
RM:682 

icon  position,  PM:287 

position,  PM:62 

size,  PM:287 

size  increment,  PM:287 
hooks   RM:225,327 

action,  PM:408 
host  access  list   PM:538 
Hyper  key    PM:202 

(see  also  modifiers.) 


ICCCM    PM:1 1, 283, 303,  306, 

312-317 
icon    creating;  pixmap, 

PM:292-293 
pop-ups,  PM:286 
setting;  name,  PM:292; 
pixmap,  PM:283, 292 
starting  application  as,  PM:287 
icon  size  and  position    PM:460 
iconic  option    (-iconic),  PM:93 
identiHer   PM:539 
ifndef  statement   PM:141 
implementation  file    (see  widget) 
include  Hies    PM:32, 54,  59, 138, 

141 
in  widget  implementation, 

PM:145 

incremental  selections   PM:317 
inferiors   PM:539 
inheritance    about,  PM:  19,  52, 
59, 151-160, 539;  RM:682 
adding  features  to  superclass, 

PM:160 

among  Athena  Widgets,  PM:19 
among  Motif  widgets,  PM:419 
among  Open  Look  widgets, 

PM:419 
in  widget  class  and  instance 

record,  PM:139-140 
ofAT&T,PM:425 
of  chained  methods,  PM:154 
of  conflicting  methods,  PM:160 
of  Core  resources,  PM:57,  59 
of  self-contained  methods, 

PM:154 
of  superclass  method,  PM:157 


resources,  PM:145,  147-148 
styles,  PM:154-155 
using  Xtlnherit  constants, 

PM:154 
widget  not  using  resource  value, 

PM:62 

initial  size    PM:325 
initialize  method    PM:169-174, 
306, 328, 480;  RM:493-495 
about,  PM:  170 
Constraint,  PM:341 
creating  GCs  in,  PM:172 
example  from  BitmapEdit, 

PM:172 

initialize_hook  method    PM:279 
input   from  file,  PM:23 1  -233 
from  pipe,  PM:233-234 
input  events  method, 

RM:397-398 
input  focus,  PM:539 
input  manager,  PM:539 
input  source  masks,  PM:231 
InputOnly  window,  PM:539 
InputOutput  window,  PM:155, 

539;  RM:672 
input  queue    determining  events, 

RM:106,278 
examining  head,  RM:  104- 105, 

277 

XtAppNextEvent,  RM:103 
XtAppPeekEvent,  RM:  104-105 
XtAppPending,  RM:106,  278 
XtPeekEvent,  RM:277 
insert_child  method   PM:322; 

RM:499 

insert_position    RM:407 
instance    about,  PM:  18, 539 
record,  PM:138; 
adding  variables  to,  PM:142; 
allocating  storage,  PM:142; 
BitmapEdit  widget, 

PM:141-142; 
contents,  PM:  139 
structures,  PM:138-165, 170; 

constraints  in,  PM:338 
Inter-Client  Communication 
Conventions  Manual    (see 
ICCCM) 

Intrinsics  PM:145 
about,  PM:9, 540 
intrinsic  classes;  introduction  to, 

RM:423-428 
Intrinsic.h  header  file,  PM:32 
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IntrinsicP.h  header  file,  PM:145 
selection  timeout,  RM:112 


key  events    (see  events  or  transla 
tions) 
key  translation   registering, 

RM:318 

XtKeyProc,  RM:402-404 
XtSetKeyTranslator,  RM:318 
keyboard    (see  also 
accept_focus.) 
keyboard  focus   PM:289; 

RM:473 

about,  PM:288, 404-405 
accept/reject  method,  RM:387 
redirecting  input,  RM:316-317 
setting,  PM:289 
styles,  PM:289,  540 
window,  RM:674 
(see  also  accept_focus;  XtNinput 
resource;  XtSetKeyboard- 
Focus.) 

keyboard  grabbing    (see  grabs) 
keyboard  mapping   RM:689 
keyboard  shortcuts    (see  acceler 
ators) 
keycodes   about,  PM:  198, 406, 

540 
translating;  keycode-to-keysym, 

RM:337-340; 

XtTranslateKey,  RM:337-338; 
XtTranslateKeycode, 

RM:339-340 

KeymapNotify  event   RM:683 
KeyPress  event  PM:201 
KeyRelease  event   PM:201; 

RM:684-686 
keysyms   about,  PM:  198, 406, 

540 
converting  case,  PM:205; 

RM:379-380 

determining  case,  RM:167 
key  generated,  PM:203 
keysymdef.h  header  file, 

PM:  199, 202 

naming  conventions,  PM:199 
XtCaseProc,  RM:379-380 
XtConvertCase,  RM:167 


Label  widget   PM:19, 30, 75, 118, 

181, 248, 323, 366, 464 
Label.hfile,PM:31 
labels   setting,  PM:53 
language  portability   PM:52 
layout  Form  method    PM:340 
LeaveNotify  event   PM:200-201, 

242, 365-366 
LeaveWindow  event   PM:222, 

374, 378 
lint   PM:45 
List  widget  PM:20,436 

class,  PM:20, 222 
loose  bindings   PM:252,540 


M 

macros   PM:403-404 
main  loop   PM:32,36 
customizing  example,  PM:241 
internals,  PM:241 
XtAppMainLoop,  RM:102 
XtMainLoop,  RM:243 
MapNotify  event   RM:687-688 
mapping   PM:197 
about,  PM:59, 540 
button,  RM:689 
keyboard,  RM:689 
pop-up  shell;  XtPopup', 

RM:280-281 
unmapping  pop-up  shell;  XtPop- 

down,  RM:279 

widgets;  XtMapWidget,  RM:252 
(see  also  MappingNotify  event; 

widget,  mapping.) 
MappingNotify  event 

RM:689-690 

MapRequest  event   RM:691 
mechanism  without  policy 

PM:10,283 

memory  allocation   PM:408 
for  widget  instance  record, 

PM-.152 
menus   about,  PM:36, 357-395, 
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accelerators  in,  PM:379, 383 
cascaded,  PM:359, 374-379 
drop-down,  PM:359, 371-373; 

example,  PM:372-373 
operation  of,  PM:361 
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panes  in,  PM:361 

pointer  grabbing,  PM:363,  365 

popping  down,  PM:363,  371, 

379; 

MenuPopdown,  RM:253 
popping  up,  PM:369; 

MenuPopup,  RM:254-255 
popping  up  with  callbacks, 

PM:371 

puU-down,  PM:359 
SimpleMenu  widget,  example, 

PM:380, 382 

spring-loaded,  PM:359,  363 
XtMenuPopdown  action, 

PM:365 

XtMenuPopup  action,  PM:365 
messages    about,  PM:3 1,541 

OOPvs.Xt,PM:31 
Metakey   PM:202 
methods    about,  PM:  155-157, 541 
accept_focus,  PM:156,  404-405; 

RM:473; 
about,  PM:531 

and  instance  structure,  PM:139 
change_managed,  PM:322-324, 

332, 349;  RM:474; 
about,  PM:533; 
in  constraint  widgets, 

PM.-349-350 
class_initialize,  PM:156,  270, 

394;  RM:476; 
about,  PM:534 
class_part_initialize,  PM:156; 

RM:477 

Constraint;  destroy,  RM:481; 
initialize,  PM:342;  RM:496 
Constraint  set_values, 

RM-.513-514 
constraint  widgets;  destroying, 

PM:340; 

initializing,  PM:341; 
resizing,  PM:347 
constraint_destroy,  RM:437 
declarations  in  widget  implemen 
tation  file,  PM:  150 
delete_child,  PM:322, 335; 

RM:478; 
about,  PM:535 
destroy,  PM:157, 169, 187,  340; 

RM:479; 
about,  PM:536; 
example,  PM:  187 
display_accelerator,  PM  :2 1 6 ; 


RM:482 
drawing;  due  to  changes  in 

set_values,  PM:180; 
in  expose,  PM:  170 
expose,  PM:31, 156, 169-170, 
175-178, 226, 537; 
RM:484-485; 

in  gadget  parent,  PM:391-392; 
in  gadgets,  PM:386, 391; 
XtExposeProc,  RM:438, 

483-486 

Form  layout,  PM:340 
gadget;  expose,  PM:391; 
query_geometry,  PM:391; 
set_values_almost,  PM:391 
geometry_manager, 

PM:322-323, 343;  RM:487 
get_values_hook,  PM:157,  216, 
279,479;RM:491-492,491, 
517; 

about,  PM:538; 
example,  PM:279;  RM:491 
inOOP,PM:31 
inheritance;  adding  to  super 
class,  PM:  160; 
of  superclass,  PM:  157 
initialize,  PM:155, 169-174, 170, 

341;RM:493-495; 
about,  PM:539; 
caUing  XInternAtom, 

PM:169-174, 170,328; 
example,  PM:170, 172; 
in  constraint  widget,  PM:341 
initializejiook,  PM:155, 279; 

about,  PM:539 
insert_child,  PM:322;  RM:491, 

499; 

about,  PM:539 
insert_jx>sition,  PM:335; 

RM:499 

layout  Form,  PM:340 
not  known  to  Xt,  PM:340 
query_geometry,  PM:157, 169, 

184-186, 322;  RM:501; 
about,  PM:169, 184-186, 322, 

544; 

in  constraint  widget, 
PM:329-330,351; 
in  gadgets,  PM:350,  391 
realize,  PM:  156,  288,  328; 

RM:505-507; 
about,  PM:544 
reconciliation,  PM:160 
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resize,  PM:  156, 169, 181-183, 

322,  325,  347;  RM:508; 
about,  PM:545; 
in  composite  widget,  PM:329; 
in  constraint  widget, 

PM:347-348; 
in  gadget  parent,  PM:393 
resources  and  set_values, 

PM:178-181 

set_values,  PM:156, 169-170, 
178-181,328-329,349; 
RM:510-512; 
about,  PM:547; 
redrawing,  RM:434 
set_values_almost,  PM:334-335; 

RM:515-516; 
about,  PM:547; 
in  gadgets,  PM:156,  391 
set_values_hook,  PM:156, 

279-280;  RM:5 17-5 18,  5 17; 
about,  PM:547 

minimal  useful  size    PM:330 
mkfontdir   PM:458 
Mod  keys   PM:202 

(see  also  modifiers.) 
modal  cascade    PM:360 
modal  pop  ups   PM:360 
modiHers    !,  PM:205 
adding,  PM:203 
and  event  sequences,  PM:207 
case-specifics,  PM:205 
colon,  PM:205-206 
displaying  list,  PM:203 
for  button  events,  PM:208 
keys,  PM:201 -206,  541; 

RM:712-719 

matching  exactly,  PM:205 
negating,  PM:204 
None,  PM:205 
monochrome    PM:541 
Motif  PM:361,419,422 
motion  compression    PM:242 
MotionNotify  event   PM:201, 

222,  242, 366;  RM:692-694 
multiple  click  timing    PM:207 
multiple  toplevel  shells    PM:413 


N 


name  option    (-name),  PM:93 
naming  conventions   widgets, 


PM:463 

new-lines    in  translations,  PM:194 
nonfatal  error   PM:197 
registering  method,  RM:115 
registering  procedure,  RM:329, 

331 

(see  also  error;  error  handling.) 
nonmaskable  events    (see  events) 
non-widget  objects   RM:423 
notify  method    PM:394 
notify  modes    (see  translations) 


O 


object   RM:443-446 
about,  PM:30, 541 

Object  class,  PM:387;  RM:423 

object-oriented  programming, 

PM:541 

objectCIass   RM:444 
ObjectClassPart   RM:443 
ObjectClassRec    RM:444 
object-oriented  programming 

PM:ii,  30-3 1,226 
ObjectPart   RM:444 
ObjectRec    RM:445 
obscure    PM.-541 
occlude    PM:541 
OOP    (see  object-oriented  pro 
gramming) 

optimization    PM:125, 183,411 
options    abbreviating,  PM:92 

argument  styles,  PM:95 

-background,  PM:92-93 

-background  (-bg),  PM:447 

-bd,  PM:93 

-bg,  PM:92-93 

border  (-bd),  PM:447 

-bordercolor,  PM:93 

-borderwidth,  PM:93 

-bw,  PM:93 

command  line,  PM:91; 
styles,  PM:95 

custom,  PM:254 

defining  your  own,  PM:93 

-display,  PM:93 

-fg,  PM:93 

-font,  PM:93 

-foreground  (-fg),  PM:447 

-geometry,  PM:288, 458-460 

handling  errors  in,  PM:96 

-iconic,  PM:93,  287 
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options  table;  example,  PM:94; 

xbitmap,  PM:108 
overriding  standard,  PM:96 
-rv/+rv,  PM:93 
-sectionTimeout ,  PM:93 
-selectionTimeout,  PM:93 
standard,  PM:9 1-92 
-synchronous,  PM:93 
-title,  PM:93 
-xrm,PM:9 1,254 
OR  operator   RM:71, 120,  298, 

302 

OverrideShell   RM:447 
OverrideShell  widget  class, 

PM:286;  RM:452-460 
overrideShellWidgetClass, 

PM:79 

overriding   override_redirect  win 
dow  attribute,  PM:159 
redirect,  PM:286 
standard  options,  PM:96 
translations,  PM:50-51 


padding    PM:542 
Paned  widget   PM:20,  70 
parent   about,  PM:542 

parent  window,  PM:542 
parsing   command-line  argu 
ments,  PM:93-96 

translations,  PM:51 
part  (vs.  record)    PM:  140 
passive  grab    PM:364 
path  resources   PM:255 
pipe  input   PM:233-234 
pixel  values    about,  PM:  121,  542 
pixmap    about,  PM:58, 175, 542; 
RM:483 

freeing,  PM:187 

icon,  PM:292 

updating  in  widget,  PM:118 

XYPixmap  format,  PM:549 

ZPixmap  format,  PM:550 
plane   PM:542 

plane  mask,  PM:542 

(see  also  bit  plane.) 
pointer   PM:363,542 

about,  PM:3 

dereferencing,  PM:535 

pointer  events  (see  events  or 
translations) 


pointer  grabbing;  about,  PM:542 
pointing  device,  PM:542 
(see  also  grabs.) 

popups    about,  PM:17,  75,  543 
cascading;  about,  PM:357 
creating  in  work  procedure, 

PM:240;  RM:420 
creating  just  before  popping  up, 

PM:81 

from  callback  function,  PM:79 
linking  group,  PM:286 
modal,  PM:360; 
about,  PM:541 
modeless,  PM:360; 

about,  PM:541 
moving  to  desired  position, 

PM:80 

OverrideShell,  PM:286 
sensitivity,  PM:385 
spring-loaded,  PM:360,  547 
using,  PM:75-76,  79 
when  application  is  iconified, 

PM:286 

pop-up  menus  PM:357 
example,  PM:366,  369 
(spring-loaded)  using  Box 

widget,  PM:366,  369-370 
pop-up  shell   creating, 

RM:171-173 
mapping,  RM:280-281 
unmapping,  RM:279 
(see  also  XtCreatePopupShell.) 
portability    PM:99, 23 1 ,  389, 

407,410-411 

position    about,  PM:62, 265 
hints,  PM:287 

relative  to  root  window,  PM:294 
setting  with  resources,  PM:61 
PRIMARY  selection    PM:296 
printer  fonts   (see  fonts) 
private  header  file 

BitmapEdiP.h,  PM:138-143 
private  instance  variables 

PM:142 
process  input   RM:102 

XtAppMainLoop,  RM:102 
program  structure  PM:32 
properties  about,  PM:294, 543 

and  atoms,  PM:303 
PropertyNotify  event   RM:695 
protocol    PM:5 
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PseudoColor   PM:543 
public  functions   PM:161 

about,  PM:  107 

naming  conventions,  PM:116 

reasons  to  use,  PM:109 
public  header  Tile    PM:32,391 

BitmapEdith,  PM:138, 160-162 
public  instance  variables   (see 

resources) 

public  routines   PM:351 
pull-down  menu   PM:359 


quarks   PM:276,543 
query_geometry  method 

PM:157, 184-186,391; 

RM:501 
about,  PM:  184 
example  from  BitmapEdit, 

PM:186 

gadgets  in,  PM:391 
in  gadgets,  PM:350-351 


raise   PM:544 

raw  event  handlers   PM:227; 
RM:76-77 

(see  also  events.) 
realization   PM:35 

about,  PM:176, 180 
realize  method    PM:154, 159, 
288, 328, 480;  RM:505-507 

about,  PM:  157 
RealizeProc    RM:438 
rectangle   PM:544 
RectObj  class   PM:  158, 387, 390; 

RM:423, 448-451 
RectObjClass   RM:450 
RectObjClassPart   RM:449 
RectObjClassRec    RM:450 
RectObjPart   RM:450 
RcctObjRcc    RM:450 
redrawing  windows   PM:25, 175 
reference  pages   list,  RM:617 
regions   PM:  178, 392;  RM:72, 

485 

registering   callbacks,  RM:65-66; 
list,  RM:67-68 

converters,  PM:269-274;  RM:69, 


83-85, 290 
event  handlers,  PM:224-226; 

RM.-70-71 
fatal  error  condition  procedure, 

RM:110,314 
fatal  error  procedure,  PM:156, 

399-402;  RM:  109 
file,  RM:75,  86-87 
nonfatal  error  condition  proce 
dure,  RM:  114, 315, 329, 331 
nonfatal  error  procedure, 
PM:399-402;RM:115 
raw  event  handler,  RM:76-77 
work  procedure,  RM:79,  89 
registering/declaring  actions 

(see  actions) 
Release  4  (R4)   PM:i,  36, 116, 

200, 289, 357, 359, 385, 414 
compared  to  R3,  PM:467-493 
initialize_hook  and  set_val- 
ues_hook  obsolescence, 
RM:49 1,497 
removing   callbacks, 

RM:295-297 
grabs,  RM:300 
input,  RM:301 

raw  event  handlers,  RM:302-303 
timeouts,  RM:304 
reparenting   PM:544 
about,  PM:293, 373 
(see  also  window  manager.) 
ReparentNotify  event  RM:696 
reply   PM:544 
representation  type   PM:86, 88 

about,  PM:247, 249, 545 
resize  method   PM:169, 181-183, 

322;  RM:508 
about,  PM:  181 
example  from  BitmapEdit, 

PM:183 

in  gadgets,  PM:393 
ResizeRequest  event   RM:697 
resizing   PM:322 
about,  PM:69, 169, 181-183, 321 
caching  old  size,  PM:183 
parent  widget,  RM:508 
(see  also  events,  ResizeRequest; 

methods,  resize.) 
resource   conversion,  RM:184 
resource  database   obtaining  for 

display,  RM:  179 
(see  also  XtDatabase.) 
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resource  list   copying;  from 

ArgList,  RM:323-324 
copying  to  argument  list, 

RM:223-224 
copying;  (see  also  XtGetSub- 

values;  XtSetSubvalues.) 
default  values;  retrieving, 

RM:211-212 
retrieving;  (see  also 

XtGetResourceList.) 
updating,  RM:201-203; 

by  name  or  class,  RM:221-222 
(see  also  XtGetSubResources; 

XtGetApplicationResources.) 
Resource  Manager  (see  actions) 
resources  about,  PM:23-24, 34, 

38,52,57,59,248-251,545; 

RM:43 1-432 
and  set_values  method, 

PM:178-181 
application,  PM:85 
caching,  PM:271 
changing  value,  PM:178 
checking  validity,  PM:170 
classes  and  instances,  PM:88 
comment  character  in  files, 

PM:253 

constraint,  PM:73;  RM:434-437 
copying;  from  ArgList  to  widget, 

RM:327-328; 
from  widget  to  argument  list, 

RM:225-226; 

XtGetValues,  RM:225-226; 
XtSetValues,  RM:327-328 
default  address;  interpreting, 

PM:251 
default  value;  converting, 

PM:267; 

setting,  PM:88, 267 
defined  by  Core,  PM:57 
defined  in  widget  implementa 
tion  file,  PM:145, 147-148 
defining  characteristics, 

PM:88-89 
defining  in  widget,  PM:145, 

147-148 

fallback,  PM:258 
Form  widget,  PM:73,  337 
format;  of  definitions, 

PM:252-253 

getting  from  application,  PM:52 
hardcoding  advantages,  PM:40 
in  instance  record,  PM:142 


inheritance  of,  PM:52,  145, 

147-148 
interactions  between,  PM:60,  62; 

example,  PM:60 
loading;  from  .Xdefaults  file, 
PM:60; 

with  xrdb,  PM:60 
looking  up  values,  PM:25 1-263 
loose  bindings,  PM:252 
name,  PM:88 

naming  conventions,  PM:248 
precedence  rules,  PM:260-263 
representation  types,  PM:86,  88, 

249 
resource  conversion,  PM:88; 

converters  in  Xmu,  PM:266; 

method,  RM:408; 

registering,  PM:270; 

XtConverter,  RM:383-386; 

(see  also  XtResourceDe- 

faultProc.) 
resource  database,  PM:545; 

sources,  PM:253 
resource  file  format,  RM:709 
resource  list;  declaring,  PM:248; 

example,  PM:87-88; 

format,  PM:88-89 
Resource  Manager,  PM:545 
resource  setting,  PM:545 
resource  value;  getting,  PM:57 
retrieving;  application  resources, 
PM:90-91; 

resource  default  at  run-time, 

PM:268 
RESOURCE_MANAGER  property, 

PM:254 

setting;  for  multiple  widgets, 
PM:68; 

for  widget  hierarchy,  PM:68; 

in  application,  PM:52; 

with  XtSetValues,  PM:54; 

XtNinput,  PM:290 
size,  PM:251 
sources  priority,  PM:254 
specifications,  PM:260-263,  545; 

errors  in,  PM:39; 

format,  PM:39-40; 

merging  of  duplicate, 
PM:253-255; 

wildcards  in,  PM:252 
symbolic  constants,  PM:40, 54 
tight  bindings,  PM:252 
type  conversion,  PM:40,  263-278 
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type  converter,  XtConvert, 

RM:142-143 
types  table,  PM:249 
use  of  classes,  PM:249 
XtN  constants,  PM:  160 
XtNaccelerators  (Core),  PM:58 
XtNallowShellResize  (Shell), 

PM:286 
XtNancestorSensitive  (Core), 

PM:58 

XtNargc  (SheU),  PM:285-286 
XtNargv  (SheU),  PM:285-286 
XtNbackground  (Core),  PM:58 
XtNbackgroundPixmap  (Core), 

PM:58 
XtNbaseHeight  (Shell), 

PM:286-287 

XtNbasewidth  (SheU),  PM:286 
XtNbaseWidth  (Shell),  PM:287 
XtNborderColor  (Core),  PM:58 
XtNborderPixmap  (Core),  PM:58 
XtNborderWidth  (Core),  PM:58 
XtNcolormap  (Core),  PM:58 
XtNcreatePopupChildProc 

(Shell),  PM:285 
XtNdefaultDistance  (Form), 

PM:336 

XtNdepth  (Core),  PM:58 
XtNdestroyCallback  (Core), 

PM:44, 58 
XtNgeometry  (Shell), 

PM:285-286, 288 
XtNheight  (Core),  PM:58 
XtNheightlnc  (Shell), 

PM:286-287 
XtNhorizDistance  (Constraint), 

PM:336 

XtNiconic  (SheU),  PM:285, 287 
XtNiconMask  (SheU),  PM:286 
XtNiconName  (Shell),  PM:286, 

292 
XtNiconPixmap  (SheU),  PM:286, 

292 
XtNiconWindow  (SheU), 

PM:286 

XtNiconX  (SheU),  PM:285, 287 
XtNiconY  (SheU),  PM:285, 287 
XtNinitialState  (SheU),  PM:286 
XtNinput  (SheU),  PM:286, 

288-290 
XtNinsertPosition  (Composite), 

PM:335 
XtNmappedWhenManaged 


(Core),  PM:58, 332 
XtNmaxAspectX  (SheU), 

PM:286-287 
XtNmaxAspectY  (SheU), 

PM:286-287 
XtNmaxHeight  (SheU), 

PM:286-287 
XtNmaxWidth  (Shell), 

PM:286-287 
XtNminAspectX  (SheU), 

PM:286-287 
XtNminAspectY  (SheU), 

PM:286-287 
XtNminHeight  (SheU), 

PM:286-287 
XtNminWidth  (SheU), 

PM:286-287 
XtNoverrideRedirect  (SheU), 

PM:285-286 

XtNpixmap  (Core),  PM:118 
XtNpopdownCallback  (SheU), 

PM:371 
XtNpopupCaUback  (Shell), 

PM:37 1,373 

XtNsaveUnder  (SheU),  PM:286 
XtNscreen  (Core),  PM:58 
XtNsensitive  (Core),  PM:58 
XtNtitle  (SheU),  PM:285, 292 
XtNtransient  (Shell), 

PM:285-286 
XtNtranslations  (Core),  PM:49, 

51,58,114 
XtNvertDistance  (Constraint), 

PM:336 
XtNwaitForWm  (SheU), 

PM:285-286 
XtNwidth  (Core),  PM:58 
XtNwidthlnc  (Shell), 

PM:286-287 
XtNwindowGroup  (SheU), 

PM:285-286 
XtNwmTimeout  (SheU), 

PM:285-286 

XtNx  (Core),  PM:58 

XtNy  (Core),  PM:58 

(see  also  resource  list.) 

resources  conversion 

XtDirectConvert,  RM:184 
reverse  option  (-rv/+rv)   PM:93 
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RGB    color  model,  PM:449-450 
root  window   PM:58, 79, 288, 

294, 369, 404, 546 
root_geometry_manager 

PM:479 
root_geometry_manager  method 

RM:455 

round  trip  request   PM:32 
rubber-band  outline    PM:  181, 

302 


save_under  window  attribute 

PM:159 

saving  under   PM:159 
scan  line   PM:546 
screen   PM:3 
about,  PM:6,  546 
example  of  typical  X  Window, 

PM:5 

layout  of,  PM:287 
monochrome,  PM:173 
screen  fonts;  (see  fonts) 
specifying  default,  PM:413 
scrollbars    about,  PM:  15,  68,429, 

441,547 
adding  to  application,  PM:1 1 1 ; 

example,  PM:111 
adding  to  xbitmap,  PM:  111 
and  Expose  events,  PM:116 
calculating  thumb  size, 

PM:115-117; 
example,  PM:1 15-1 17 
creating,  PM:113 
Scrollbar  widget,  PM:15,  20,  44, 

70,110-113,269 
selection  data   RM:  185,  269-270 

(see  also  XtOwnSelection.) 
selection  timeout   (see  timeouts) 
SelectionClear  event   RM:698 
SelectionNotify  event   RM:699 
So  lection  Request  event   RM.700 
selections   PM:198, 283, 294-318, 

294, 547 

adding  to  clipboard,  PM:316 
and  CurrentTime,  PM:304 
asserting  ownership, 

PM:303-304 
converting;  example, 

PM:308-309,  315-316; 
selection,  PM:307-309; 


standard  selections, 

PM:314-316;RM:390,392 
deleting,  PM:316 
disowning,  PM:318 
handling  large  selections, 

PM:316;  RM:392 
highlighting,  PM:298,  302-303; 

example,  PM:299,  302-303 
incremental,  PM:317 
losing  selection,  PM:304,  312 
pasting,  PM:307; 
example,  PM:310-3  11; 
selection,  PM:3  10-3  11 
querying  for  desired  target, 

PM:313-317 
requesting  selection, 

PM:304-305 
selection  data;  method, 


obtaining,  RM:215; 
obtaining  in  multiple  formats, 

RM:218-219; 
(see  also  XtGetSelection  Value; 

XtGetSelection  Values  .), 
XtConvertSelectionProc, 

RM:389-392; 

XtDisownSelection,  RM:185 
selection  method  XtSelection- 
DoneProc;  (see  also  XtSelec- 
tionCallbackProc; 
XtLoseSelectionProc; 
XtSelectionDoneProc.) 
selection  timeout  (see  timeouts) 
setting  timeout,  PM:318 
target  types,  PM:305-307 
XA.CLIPBOARD,  PM:303, 

316-317 
XA_MULTIPLE,  PM:316; 

RM:392 

XA_PRIMARY,  PM:296,  303 
XA_SECONDARY,  PM:303 
XA_TARGETS,  PM:306,  313 
(see  also  events,  SelectionRe- 
quest;  SelectionClear  event; 
SelectionNotify  event;  Selec- 
tionRequest  event) 
self-contained  methods   (see 

inheritance) 

sensitivity   PM:59,  81,99,  243 
checking  state;  XtlsSensitive, 

RM:233 
in  pop-up  callbacks,  PM:385 
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setting  state;  XtSetSensitive, 

RM:322 

server    about,  PM:6, 547 
round  trip  request,  PM:546 
server  code;  guide  to,  PM:527 
server  grabbing,  PM:547 
server  request,  PM:545 
server  resources;  freeing, 

PM:187 
set_values   (see  also  XtSet- 

Values.) 

set_values  method    PM:156, 
169-170,178-181,328-329; 
RM:510-512 
about,  PM:178 
example  from  BitmapEdit, 

PM:179 

set_values_almost  method 
PM:391;RM:515-516 
in  gadgets,  PM:156 
set_values_hook  method 
PM:  156, 279-280; 
RM:517-518 

Shell   PM:254;  RM:452-460 
Shell  types;  ApplicationShell, 

RM:453; 

OverrideShell,  RM:453; 
Shell,  RM:453; 
TopLevelShell,  RM:453; 
TransientShell,  RM:453; 
VendorShell,  RM:453; 
WMShell,  RM:453 
Shell  widget,  PM:17,  65, 106; 

about,  PM:21 
Shell  widget  class;  about, 

PM:  17, 34,  6 1,65, 70, 283 
ShellClassPart,  RM:454-456 
ShellPart,  RM:457-459 
(see  also  environment  variables.) 
Shell  widget  class   RM:517 
about,  RM:452-460 
reason  for  invisibility,  PM:67 
resources,  PM:285-291, 293-294 
root_geometry_manager  method, 

RM:455 

subclass;  XtlsSheU,  RM:234 
types,  RM:453 
XtNbasewidth,  PM:286 
sibling   PM:547 
Simple  widget   PM:19,420 
SimpleMenu  widget   PM:361, 


379-383,391-395 
single-line  input  field   PM:294 
sink   in  Athena  Text  widget, 

PM:278 
size    PM:321 
hints,  PM:287 
preferences,  PM:333 
sizeof,PM:152 
Sme  gadgets   PM-.379-391 
software  architecture   PM:8 
source   code;  obtaining,  PM:36 
files  for  widget,  PM:138 
in  Athena  Text  widget,  PM:278 
source  compatibility    PM:41 4 
spring-loaded  menu 

PM:363-371 
vs.  drop-down,  PM:360 
spring-loaded  pop  up    (see  pop 

ups) 

stacking  order   PM:322, 352, 547 
standard  colormaps   Xmu  utili 
ties,  PM:291 
StaticColor   PM:548 
StaticGray   PM:548 
status   PM:548 
stdio.hfile    PM:145 
stipple    PM:548 
storage    allocating,  RM:248; 
for  data  type,  RM:260; 
XtNew,  RM-.260 
XtMalloc,  RM:248     , , 
storage  block   freeing,  RM:198 
resizing;  XtRealloc,  RM:289 
(see  also  XtFree.) 
string   copying;  XtNewString, 

RM:261 
error  message;  XtStringConver- 

sion Warning,  RM:333 
StringDefs.h  header  file,  PM:88; 

RM:721 
string  to  bitmap  converter 

PM:269 
StringDefs.h  header  file    PM:32, 

54, 145, 269 
strings   setting,  PM:53 
StringToWidget  resource  con 
verter   PM:73 
structure   determining  field's 

byte  offset,  RM:264 
(see  also  XtOffset.) 
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structure  of  Xt  applications 

PM:32 
subclass   PM:19 

about,  PM:548 
submenus   PM:377 

cascading,  PM:379 

creating,  PM:376 

popping  up,  PM:84, 375 

(see  also  XtPopup.) 
subparts   PM:152, 157,278-280 
subresources   PM:152, 157, 
278-280 

managing,  PM:279-280 
Super  key   PM:202 

(see  also  modifiers.) 
superclass   PM:152, 179 

about,  PM:  19, 548 

class  structure,  PM:140 

gadget,  PM:390 

inheritance,  PM:59 

ofCore,PM:387 
synchronous  option    (-synchro- 
nous/+synchronous),  PM:93 
syntax  functions   PM:96 


TCP/IP   PM:295 

Text  widget   PM:20-21, 79, 153, 

294, 433, 443 

tight  bindings    PM:252,548 
tilde   PM:204 
tiling   PM:58 

about,  PM:548 
time   PM:548 
timeouts   about,  PM:234 
adding,  PM:234 
and  visibility  interest,  PM:237 
callback  method,  RM:413 
example,  PM-.235-236 
invoking  procedure  after  timeout, 

RM:88 

removing,  PM:236-237 
selection  timeout;  setting, 

RM:321; 

value,  RM:99, 112,214 
XtAddTimeout,  RM:78 
XtAppAddTimeOut,  RM:88 
XtAppSetSelectionTimeout, 

RM:112 

XtGetSelectionTimeout,  RM:99, 
214 


XtRemoveTimeOut,  RM:304 
XtSetSelectionTimeout,  RM:321 
XtTimerCaUbackProc,  RM:413 
timing   multiple  clicks,  PM:207 
title  option    (-title),  PM:93 
toolkits    initializing  internals, 

RM:335 
initializing  toolkit  and  display, 

RM:234-238 
Xtlnitialize,  RM:234-238 
XtToolkitlnitiaMze,  RM:335 
top-level 

topLevelShellWidgetClass, 
RM:452-460 
widget,  PM:34; 

(see  also  Shell  widget.) 
window,  PM:548 
topLevelShellWidgetClass 

PM:284 

training   PM:525 
TransientShellWidgetClass 

PM:75 
transientShellWidgetClass 

PM:79 
TransientShellWidgetClass 

PM:284 
transientShellWidgetClass 

RM:452-460 
Translation  Manager   (see 

actions) 
translations   PM:213 

#  augment  directive,  PM:50 
!  modifier  symbol,  PM:205 

#  override  directive,  PM:50 

#  replace  directive,  PM:50 
about,  PM:29, 41, 46, 49, 59, 548 
augmenting,  PM:50-51 

colon  modifier  symbol, 

PM:205-206 

compUing;  table,  RM:275-276; 
when  widget  class  initialized, 

PM:149; 
XtParseTranslationTable, 

RM:275-276 
defining;  default  in  Core  class 

part,PM:153; 
in  source,  PM:51 
details  in,  PM:  198-201 
differences  between  directives, 

PM:195 

double-clicks,  PM:206 
event  abbreviations,  PM:  196-197 
event  sequences,  PM: 206 -208 
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hardcoding,  PM:51 

in  widget  implementation  file, 

PM:148-149 
inheritance,  PM:148 
interactions  between, 

PM:208-213 

keyboard  events,  PM:  198-199 
merging,  PM:  114,  209; 

widget  translations,  RM:1 19 
merging/overwriting,  RM:268 
modifiers,  PM:201-206,  203; 

and  event  sequences,  PM:207 
Motion  events,  PM:207 
newlines  in,  PM:194 
*Notify  details,  PM:200 
order,  PM:209 
overriding,  PM:50-51 
parsing,  PM:51 
removing,  RM:345 
replacing,  PM:50-51 
resource  converters,  PM:265 
syntax,  PM:194 
tilde  modifier  symbol,  PM:204 
translation  table,  PM:549; 

RM:711; 
example,  PM:49 

XtAugmentTranslations,  RM:119 
XtUninstallTranslations,  RM:345 
(see  also  accelerators;  actions; 

XtOverrideTranslations.) 
traversal   post-order,  PM:543 

pre-order,  PM:543 
TrueColor   PM:549 
type  converters   PM:40 
about,  PMrlOO 
explicitly  invoking,  PM:274-275; 

example,  PM:274-275 
format,  PM:275-278 
passing  arguments  to,  PM:272; 

example,  PM:272 
registering,  PM:269-274 
(see  also  resources.) 
type  property   PM:549 
typedefs   PM:142 


U 

unmanaging  widget   PM:332 
UnmapNotify  event 

RM:687-688 


upward  chaining   PM:154 
uunet   PM:36 
uwm    PM:358 


VendorShell  widget  class 

PM:289 
Viewport  widget   PM  :2 1 , 1 1 0, 

326 
virtual  colormaps   PM:  159, 290 

crossing,  RM:668 
visibility  interest   PM:153, 

237-238 
VisibilityNotify  event 

RM:701-702 

visible_interest  field    PM:237 
visual  class   PM:549 


W 

warning  handler   calling  high- 
level,  RM:117-118, 362-363 
(see  also  XtAppWarningMsg; 

XtWaming;  XtWarningMsg.) 
warnings    PM:399 
listing,  RM:703 
(see  also  error  handling.) 
widget   PM:15-17, 70, 105, 283 
about,  PM:8, 15, 549 
actions;  example,  PM:188, 190 
adding  to  parent  list,  PM:16; 

RM:249-251; 
XtManageChild,  RM:249; 
XtManageChildren, 

RM:250-251 
application  context;  getting, 

RM:364; 
XtWidgetToApplicationCon- 

text,  RM:364 
as  data  type,  PM:35 
call  accept_focus  method, 

RM:122 
child  widget;  creating/managing, 

PM:65,323;RM:170; 
layout  of,  PM:330-331 
class;  composite  widget  sub 
class,  RM:246; 
constraint  widget  subclass, 
RM:247; 
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determining  subclass,  RM:235; 
obtaining,  RM:  138; 
Shell  widget  subclass,  RM:234; 
verifying,  RM:137; 
XtCheckSubclass,  RM:137; 
XtClass,RM:138; 
XtlsComposite,  RM:246; 
XtlsConstraint,  RM:247; 
XtlsSheU,  RM:234; 
XtlsSubclass,  RM:235 
composite,  PM:21 
converting  (R3  to  R4),  PM:467 
creating,  PM:32,  85; 

RM:174-176; 
additional  top-level  widget, 

RM:90-91 
creating  additional  top-level 

widget,  RM:  169 
creating;  working  window, 

RM:177-178; 

(see  also  XtAppCreateShell; 
XtCreateApplicationShell; 
XtCreateMgdWidget; 
XtCreateWidget.) 
declaring  class  record  pointer; 

example,  PM:157 
default  size,  PM:184 
defining  conventions,  PM:138, 

252; 

summary,  PM:164 
destroying,  PM:28,  84,  187; 

RM:182-183; 
XtDestroyWidget, 

RM:182-183 
display  pointer,  RM:187; 

XtDisplay,RM:187 
dragging,  PM:20 
Exclusive  and  Nonexclusive, 

PM:426 

framework  of  code,  PM:137-165 
geometry  (see  geometry  manage 
ment) 
getting  data,  PM:107; 

example,  PM:107 
hierarchy;  creating,  PM:67 
implementation  file,  PM:138, 

143-160; 

actions  table,  PM:  148-149; 
declaration  of  methods, 

PM:150; 

resources,  PM:145, 147-148; 

translation  table,  PM:148-149 

instaUing  accelerators  (see  accel 


erators) 

instance  structure,  PM:170 
internals,  PM:137-165 
Label,  PM:270 
macros  for,  PM:403 
management,  PM:65,  184-186; 

RM:248; 

XtlsManaged,  RM:248; 
(see  also  XtManageChild; 

XtManageChildren.) 
managing  child,  PM:170-174 
mapping,  PM:59; 
changing  map_when_managed 

field,  RM:3 19; 
to  display,  RM:252 
mapping  to  display; 

XtMapWidget,  RM:252 
mapping;  windows,  PM:36; 
XtSetMappedWhenManaged, 

RM:319 

merging  translations,  RM:119 
modal  widget;  redirecting  input, 

RM:73-74, 300; 
XtAddGrab,  RM:73-74; 
XtRemoveGrab,  RM:300 
moving;  XtMoveWidget, 

RM:257 
moving/resizing,  PM:58; 

RM:140-141; 
XtConfigure  Widget, 

RM:140-141 

naming  conventions,  PM:463 
necessary  include  files,  PM:138 
parent,  PM:  113 
parent  widget;  returning, 

RM:273; 

XtParent,  RM:273 
popping  down;  Menupopdown, 

RM:253 
popping  up,  PM:80-81; 

Menupopup,  RM:254-255 
private  header  file,  PM:  138-143, 

138 
public  header  file,  PM:138, 

160-162 
realizing,  PM:180;  RM:231, 

287-288; 

XtIsRealized,RM:231; 
XtRealizeWidget,  RM:287-288 
record  size,  PM:152 
removing,  PM:16; 
XtUnmanageChild,  RM:346; 
XtUnmanageChildren,  RM:347 
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resizing,  PM:69, 181-183, 
322-328;  RM:247, 508; 
per  core  dimensions,  RM:307; 
XtMakeResizeRequest, 

RM:247; 

XtResizeWidget,  RM:306; 
XtResizeWindow,  RM:307 
retrieving  event  mask, 

RM:120-121; 
XtBuildEventMask, 

RM:120-121 
returning  screen  pointer; 

XtScreen,RM:310 
sensitivity  (see  sensitivity) 
sets;  about,  PM:8, 17-18; 
Motif,  PM:18; 
special  defaults,  PM:289 
size;  (see  also  widget,  resizing.) 
source  file,  PM:  138 
subclass;  XtlsSubclass,  RM:235 
superclass;  inheritance,  PM:59; 
obtaining,  RM:334; 
XtlsSuperclass,  RM:334; 
XtSuperclass,  RM:334 
techniques  for  writing,  PM:163 
Text,  PM:433, 443 
translating;  coordinates, 

RM:336; 

name  to  instance,  RM:259; 
window  and  display  pointer, 

RM:367; 

XtNameToWidget,  RM:259; 
XtTranslateCoords,  RM:336; 
XtWindowTo  Widget,  RM:367 
unmapping;  XtUnmapWidget, 

RM:348 

WidgetProc,  RM:438 
WidgetWrap,  PM:98 
windowless  (see  gadgets) 
windows;  destroying,  RM:349; 
returning,  RM:365; 
XtUnrealizeWidget,  RM:349; 
XtWindow,  RM-.365 
(see  also  BitmapEdit  widget; 
composite  widget;  Core 
widget;  Scrollbar  widget; 
Shell  widget;  XtCallAc- 
ceptFocus.) 

widget  callback  list   (see  call 
backs) 

widget  classes   PM:65 
about,  PM:17 
Athena,  PM:19, 42, 46, 49, 65, 


70, 248; 

(see  also  Command;  Label 
widget;  Scrollbar  widget; 
widget) 

Core  (Intrinsics),  RM:43  8-442 

inheritance  among  (Athena), 
PM:19 

Intrinsics,  PM:  16-17, 57,  61, 65, 

70, 75, 139, 284, 289; 
(see  also  applicationShell; 
composite  widget;  Core 
widget;  OverrideShell;  Shell 
widget;  topLevelShell;  Tran- 
sientShell;  VendorShell; 
widget.) 

name  defined,  PM:152 

(see  also  individual  widgets 
alphabetically;  widget,  sub 
class;  widget,  superclass.) 
widgetClass  class  pointer 

PM:120 
width   PM:325 

checking  in  initialize  method, 

PM:170 
wildcards   in  font  names,  PM:454 

in  resource  specifications, 

PM:39, 252 

window   creating  widget's  work 
ing  window,  RM:177-178 

geometry,  PM:458 

InputOutput,  RM:672 

keyboard  focus,  RM:674 

unnamed  class,  PM:388 

viewable,  PM:549 

visible,  PM:549 

visual,  PM:549 

window  gravity;  about,  PM:549 

WindowObj  class,  PM:158 

zoomed  window,  PM:550 

(see  also  XtCreateWindow.) 
window  attributes   PM:160 

about,  PM:158 

background,  PM:  158 

backing_store,  PM:158, 269 

bit_gravity,  PM:158 

border,  PM:158 

colormap,PM:159,291 

cursor,  PM:  159 

event_mask,PM:159 

override_redirect,  PM:159 

save_under,  PM:159 

setting  in  realize  method, 
PM:159-160 
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window  manager   PM:69-70, 

283-294, 321 
about,  PM:1 1,33, 549 
and  decoration,  PM:293 
and  icons,  PM:292-293 
click-to-type,  PM:288 
colormaps,  PM:290-291 
focusing  styles,  PM:200 
hints,  PM:1 1,284-294 
input  models,  PM:288 
interacting  with,  PM:284-294 
keyboard  focus,  PM:288-290 
listener,  PM:540 
pointer  focus,  PM:288 
real  estate  driven,  PM:288, 544 
redirect,  PM:544 
reparenting,  PM:293, 373, 544 
save-set,  PM:546 
screen  layout,  PM:287-288 

wm_timeout   RM:455 

work  procedures    about,  RM:79 
creating  pop  up  in,  example, 

RM:420 

registering,  PM:239-240;  RM:89 
removing,  PM:239;  RM:305 
XtAddWorkProc,  RM:79 
XtAppAddWorkProc,  RM:89 
XtAppRemoveWorkProc, 

RM:305 
(see  also  XtWorkProc.) 


X    about,  PM:3 

X  Consortium  address,  PM:526 
X  protocol,  PM:5, 295 
X  source  software,  PM:521 
XView,  PM:9 
X  Toolkit   (see  toolkits) 
XA_CLIPBOARD  atom 

PM:303 

(see  also  selections.) 
XA_MULTIPLE  property 

PM:316 
XAPPLRESDIR  environment 

variable    PM:253 
XA  PRIMARY  atom    PM:296, 

~303 

(see  also  selections.) 
XA_SECONDARY  atom 

PM:303 
(see  also  selections.) 


XAJTARGETS  atom    PM:306 

(see  also  selections.) 
Xatom.hfile    PM:303, 305 
Xaw  library   PM:17,38 
xbitmap  application   PM:106, 

497 
xbitmapl;  example, 

PM:  106-109 
xbitmap2;  example, 

PM:109-117 
xbitmapS;  example, 

PM:  11 8-124 
xbitmap4;  example, 

PM:125-134 
XChangeGC  Xlib  function 

PM:173 
XChangeKeyboardMapping 

RM:690 
XClear Area  Xlib  function 

PM:180 

xclipboard    PM:315-317 
X  Configured  indow 

RM:661-662,  697 
XConfigure Window  Xlib  func 
tion   PM:352 

XConvertSelection   RM:699 
XCopyArea  Xlib  function 

PM:123, 178, 197;  RM:485 
XCopyColormapAndFree  Xlib 

function   PM:291 
XCopyPlane  Xlib  function 

PM:123, 178, 197;  RM:485 
XCreateGC  Xlib  function 

PM:121, 170 
XCreate Window  Xlib  function 

PM:160 

Xdefaults  file    PM:60 
xedit   PM:294 
XENVIRONMENT  environment 

variable   PM:254 
xev   PM:203 
Xext  library   PM:38 
xfarewelLc   example,  PM:46-47 
xfd  (font  displayer)   PM:455 
XFlush  Xlib  function    PM:412 
XGCValues  structure    PM:173 
XGetlconSizes  Xlib  function 

PM:293 

XGetModiflerMapping   RM:690 
XGetMotionEvents    RM:694 
XGetPointerMapping   RM:690 
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XGetStandardColormap  Xlib 

function    PM:291 
xgoodbye.c  example    PM:42 
xhello.c  example    PM:33-34 
XInternAtom  Xlib  function 

PM:305-306 
Xlib  library    PM:38, 174, 178, 

180 

xload    PM:289 
XLookupString  Xlib  function 

PM:406 
XLowerWindow  Xlib  function 

PM:352 

XMapRaised    RM:691 
XMapWindow   RM:691 
xmh    PM:72,294 
xmodmap    PM:203 
XMoveResizeWindow   RM:697 
Xmu  library    PM:38, 271,314 
atom  caching;  initializing, 

PM:314 

resource  converters  in,  PM:266 
XmuConvertStandardSelection, 

PM:314-316;RM:392 
XmuInternAtom,  PM:314 
XParseGeometry  Xlib  function 

PM:288 

XQueryPointer   RM:694 
XRaiseWindow  Xlib  function 

PM:352 

xrdb    PM:60, 25 1,254 
XRectlnRegion  Xlib  function 

PM:177;  RM:485 
XRefreshKeyboardMapping 

RM:690 

XResizeWindow   RM:697 
XRestackWindows  Xlib  function 

PM:352 
Xrm   XrmOptionDescRec; 

example,  PM:94; 
structure,  PM:93 
XrmoptionlsArg  argument  style, 

PM:95 
XrmOptionKind  enum  values, 

PM:95 
XrmoptionNoArg  argument 

style,  PM:95 
XrmoptionResArg  argument 

style,  PM:95 
XrmoptionSepArg  argument 

style,  PM:95 

XrmoptionSkipArg  argument 
style,  PM:95 


XrmoptionSkipLine  argument 

style,  PM:95 
XrmoptionSkipNArgs  argument 

style,  PM:95 
XrmoptionStickyArg  argument 

style,  PM:95 

XrmStringToQuark  Xlib  func 
tion,  PM:276 

XrmOptionDescRec    RM:236 

XrmoptionNoArg  argument 
style    RM:238 

XSelcctlnput  Xlib  function 
PM:213, 222 

XSendEvent   RM:656, 699-700 

XSetErrorHandler  Xlib  function 
PM:399 

XSeflnputFocus   RM:675 
Xlib  function,  PM:405 

XSetlOErrorHandler  Xlib  func 
tion    PM:399 

XSetPointerMapping   RM:690 

XSync  Xlib  function    PM:412 

XtActionHookProc    RM:373 

XtActionProc    PM:48; 
RM:374-375 

XtAddActions   PM:394; 
RM:63-64 

XtAddCallback   PM.44, 266; 

RM:65-66 
arguments,  PM:44 

XtAddCallbacks   PM:84; 
RM:67-68 

XtAddConverter   RM:69 

XtAddEventHandler 

PM:221-222;  RM:70-71 
arguments,  PM:224 
when  to  call,  PM:224 

XtAddExposureToRegion 
RM:72 

XtAddGrab   PM:385;  RM:73-74 

XtAddlnput   PM:411;RM:75 

XtAddRawEventHandler 
PM:227;  RM:76-77 

Xt Address  address  mode  con 
stant   PM:273 

XtAddressMode  enum    PM:273 

XtAddTimeOut   RM:78 

XtAddWorkProc    RM:79 

XtAppAddActionHook    PM:408, 
411;RM:80 
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XtAppAddActions   PM:47, 49, 

148,411;RM:81-82 
XtAppAddConverter    PM:41 1 ; 

RM:83-85 
XtAppAddlnput   PM:230-232, 

411;RM:86-87 
XtAppAddTimeOut   PM:234; 

RM:88 
XtAppAddWorkProc    PM:239; 

RM:89 
XtAppCreateShell    PM:284,411, 

413;  RM:90-91 
Xt AppError   PM:400-40 1,411; 

RM:92 
XtAppErrorMsg   PM:400-401, 

411;RM:93-94 
XtAppGetErrorDatabase 

PM:411;RM:95 
XtAppGetErrorDatabaseText 

PM:411;RM:96-98 
XtAppGetSelectionTimeout 

PM.-411 
XtAppInitialize    PM:32, 92, 174, 

251,254,411;RM:100 
fallback  resources  in,  PM:257 
passing  options  table  to,  PM:96 
shell  created,  PM:79 
XtAppMainLoop    PM:32,36, 

143,237,411;RM:102 
and  multiple  application  con 
texts,  PM:412 
XtAppNextEvent   PM:241, 

41 1-412;  RM:103 
XtAppPeekEvent   PM:41 1-412; 

RM:104-105 
XtAppPending   PM:41 1-412; 

RM:106 
XtAppProcessEvent   PM:242, 

411 -412;  RM:  107 
XtAppReleaseCacheRefs 

PM:411;RM:108 
XtAppSolcctionTimeout   RM:99 
XtAppSetErrorHandler 

PM:401,411;RM:109 
XtAppSetErrorMsgHandler 

PM:401,411;RM:110 
XtAppSetFallbackResources 

PM:258,411;RM:111 
XtAppSetSelectionTimeout 

PM:411;RM:112 
XtAppSetTypeConverter 


PM:411;RM:113 
XtAppSetWarningHandler 

PM:401,411;RM:114 
XtAppSetWarningMsgHandler 

PM:401,411;RM:115 
XtAppTimeOut   PM:411 
XtAppWarning    PM:400-401, 

411;RM:116 
XtAppWarningMsg 

PM:400-401,411; 

RM:117-118 

XtAppWorkProc    PM:411 
XtArgsProc    RM:499 
XtArgVal   PM:99 
XtAugmentTranslations   PM:51, 

115;RM:119 
reasons  to  use,  PM:1 14 
XtBaseOffset  address  mode  con 
stant   PM:273 

XtBuildEventMask    RM:120-121 
XtCallAcceptFocus   PM:157, 

405;  RM:  122 
XtCalLActionProc    PM:408; 

RM:123 
XtCallbackExclusive    PM:84, 

365;  RM:  124-125 
XtCallbackList   RM:376 
XtCallbackNone    PM:84, 365; 

RM:126 
XtCallbackNonexclusive 

PM:84,365;RM:127 
XtCallbackPopdown    PM:365; 

RM:128-129 

XtCallbackProc    RM:376-377 
XtCallbackRec    RM:376 

format,  PM:85 
XtCallbackReleaseCacheRef 

RM:130 
XtCallbackReleaseCacheRefList 

RM:131 

XtCallCaUbackList   RM:132 
XtCallCallbacks   PM:41; 

RM:133 
XtCaUConverter   PM:27 1,275; 

RM:134 

XtCalloc    PM:187,  408;  RM:136 
XtCancelConvertSelectionProc 

PM:317;RM:378 
XtCaseProc   RM:379-380 

function  prototype,  PM:407 
XtCheckSubcIass   RM:137 


Index 


759 


XtClass   RM:138 
XtCIoseDisplay   RM:139 
XtConfigureWidget   PM:58; 

RM:140-141 

XtConvert   PM:274;  RM:142-143 
XtConvertAndStore    PM:100, 

271, 274-275;  RM:164-166 
XtConvertArgProc    RM:38 1-382 
XtConvertArgRec    PM:272 
XtConvertCase    PM:407; 

RM:167 

XtConverter   RM:383-386 
XtConvertSelectionlncrProc 

PM:317;RM:387-388 
XtConvertSelectionProc 

PM:296, 304;  RM:389-392 
XtCreateAppllcationContext 

RM:168 
XtCreateApplicationShell 

PM:411,413;RM:169 
XtCreateManagedWidget 

PM:32,  68, 101,142,251; 

RM:  170, 474 
XtCreatePopupChildProc 

PM:384 
XtCreatePopupShell   PM:79, 

284;  RM:171-173 
XtCreateWidget  PM:32, 142, 

169,251;RM:174-176,436 
hardcoding  resources  with, 

PM:99 
XtCreateWindow   PM:160; 

RM:177-178 
XtDatabase    RM:179 
XtDefaultBackground.  PM:265, 

277, 290 

XtDefaultFont  constant   PM:265 
XtDefaultForeground  constant 

PM:265, 277, 290 
XtDestroyApplkationContext 

RM:180 

XtDestroyGC    RM:181 
XtDestroyWidget   PM:169,335; 

RM:182-183,436,500 
XtDestructor   RM:393 
XtDirectConvert   RM:184 
XtDisownSelection   PM:312, 

318;RM:185 
XtDispatchEvent   PM:241; 

RM:186 
XtDisplay   PM:275;RM:187 


XtDisplaylnitialize    RM:  188-1 89 
XtDisplayOfObject   PM:404; 

RM:190 
XtDisplayStringConver- 

sionWarning   PM:276-277, 

402;  RM:  191 
XtDispIayToAppUcationContext 

PM-.412;  RM:192 
xterm   PM:288,358 
XtError   PM:411;RM:193 
XtErrorHandler   RM:394 
XtErrorMsg   PM:411; 

RM:194-195 
XtErrorMsgHandler 

RM:395-396 
xtetris   PM:234-236 
XtEventHandler   RM:397-398 
XtFUePredicate   RM:399 
XtFindFile    PM:409;  RM:196 
XtFree   PM:187, 31 1,408; 

RM:198 

XtGeometry Almost  PM:186 
XtGeometryMask   RM:245, 285, 

488,502,515 
XtGeometryNo   PM:186 
XtGeometryResult   PM:185, 

332;  RM:245, 247, 285 
XtGeometry  Yes   PM:186 
XtGetActionKeysym   PM:407; 

RM:199 
XtGetApplicationNameAnd- 

Class   PM:404;  RM:200 
XtGetApplicationResources 

PM:85, 252;  RM:201-203 
XtGetConstraintResourceList 

PM:338;  RM:204 
XtGetErrorDatabase    PM:401, 

411;RM:205 
XtGetErrorDatabaseText 

PM:401,411;RM:206 
XtGetGC   PM:121, 170, 173, 

180;  RM:207-208 
when  not  to  use,  PM:173 
XtGetKeysymTabk   PM:407; 

RM:209 

XtGetMuItiCUckTime   RM:210 
XtGetResourceLIst  PM:148, 

263;  RM:21 1-212 
XtGetSelecttonRequest   PM:316; 

RM:213 
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XtGetSelectionTimeout 

PM:318,411;RM:214 
XtGetSelectionValue    RM:215 
XtGetSelectionValuelncremental 

PM:317;RM:216 
XtGetSelectionValues   PM:296, 

304-306,313,318; 

RM:218-219 
XtGetSelectionValuesIncremen- 

tal   RM:220 
XtGetSubresources   PM:279; 

RM:221-224 
XtGetSubvalues   PM:280; 

RM:223-224 
XtGetValues   PM:24, 57,  80, 373; 

RM:225-226, 436 
XtGrabButton    PM:365, 409; 

RM:227-228 
XtGrabKey   PM:365,409; 

RM:229-230 
XtGrabKeyboard    PM:409; 

RM:231 
XtGrabNone  grab  mode 

PM:384 
XtGrabPointer   PM:364, 409; 

RM:232 
XtHasCallbacks   PM:404; 

RM:233 
X  tl  M  Alternate  I  np  ut  constant 

PM:242 

Xtlmmcdiate  address  mode  con 
stant   PM:273 

XflMTimer  constant   PM:242 
XtlMXEvent  constant   PM:242 
Xtlnherit   constants,  PM:154; 
XtlnheritDeleteChild,  PM:335; 
XtlnheritGeometryManager, 

PM:333; 

XtlnheritlnsertChild,  PM:335; 
XtlnheritRealize,  PM:158; 
XdnheritSetValuesAlmost, 

PM:334 

XtlnheritlnsertChild    RM:499 
Xtlnitialize    RM:234-238 
XtlnitlalizeWidgetCIass 

RM:239 
XtlnputCallbackProc 

RM:400-401 
XtlnsertEventHandler   PM:224; 

RM-.240 

arguments,  PM:224 
when  to  call,  PM:224 


XtlnsertRawEventHandler 

RM:241 
XflnstallAccelerators   PM:211; 

RM:242-243 
XtlnstallAUAccelerators 

PM:211,215;RM:244 
Xtlntern Atom  Xlib  function 

PM:303 

XtlsApplicationShell    RM:24S 
XtlsComposite    PM:403;  RM:246 
XttsConstraint   RM:247 
XttsManaged    PM:403;  RM:248 
XtlsObject   RM:229 
XtlsOverrideShell   RM:230 
XtlsReallzed    PM:  176, 403-404; 

RM:23 1,484 
XttsRectObj   RM:232 
XtlsSensitive    PM:404;  RM:233 
XflsSheU   RM:234 
XttsSubclass   PM:403;  RM:235 
XUsTopU'velShell    RM:236 
XtlsTransientShell   RM:237 
XtlsVendorShcll   RM:238 
XflsWidget   RM:239 
XttsWMShell   RM:240 
XtKeyProc    RM:402-404 

function  prototype,  PM:407 
XtKeysymToKeycodeList 

PM:407;  RM:241 
XtLastTimestampProcessed 

RM:242 
XtLoseSelectionlncrProc 

PM:317;  RM:405 
XtLoseSelectlonProc    PM:304; 

RM:406 

Xt.MainLoop    PM:411;  RM:243 
XtMakeGeometryRequest 

PM:333;  RM:244-246 
XtMakeResizeRequest   RM:247 
XtMaUoc   PM:187,408;RM:248 
XtManageChild   PM:35;  RM:249 
XtManageChildren   PM:32, 35; 

RM:250-251 

XtMapWidget   PM:332;  RM:252 
XtMenuPopdown    RM:253 
XtMenuPopup    PM:369; 

RM:254-255 
argument  to,  PM:370 
XtMergeArgLkts   PM:102; 

RM:256 
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XtMoveWidget   PM:58,  324, 

331;RM:257 
XtN  constants   PM:40 
XtName    RM:258 
XtNameToWidget   PM:404 
XtNbasewidth  (Shell)    PM:286 
XtNcoIormap    setting,  PM:291 
XtNcreatePopupChildProc 

resource    PM:384 
XtNew   PM:408;RM:260,517 
XtNewString   PM:408;RM:261 
XtNextEvent   PM:411;  RM:262 
XtNinitialResourcesPersistent 

PM:271 

XtNinput   setting,  PM:290 
XtNmuItiClickTime  resource 

PM:207 

XtNsensitive  resource    PM:81 
XtNumber   RM:263 
XtOffset   PM:88;RM:264 
XtOffsetOf  macro   PM:251; 

RM:265 
XtOpenDisplay   PM:413; 

RM:266-267 

XtOrderProc  prototype  proce 
dure    RM:407 
XtOverrideTranslations   PM:51, 

114-1 15;  RM:268 

reasons  to  use,  PM:114 

XtOwnSelection    PM:296, 

303-304;  RM:269-270 
XtOwnSelectlonlncremental 

PM:317;RM:271-272 
XtParent   RM:273 
XtParseAcceleratorTable 

PM:216;  RM:274 
XtParseTranslationTable 

PM:51, 115, 149,216; 

RM:275-276 
XtPeekEvent   PM:241,411; 

RM:277 
XtPending   PM:241,411; 

RM:278 

XtPointer   PM:268,389 
XtPopdown   PM:75, 365, 369; 

RM:279, 460 
XtPopup    PM:75, 365, 377; 

RM:280-28 1,460 
XtPopupSpringLoaded 

PM:365;  RM:282 
XtProc    RM:438 
XtProcedureArg  address  mode 


constant   PM:273 
XtProcessEvent   PM:411; 

RM:283 
XtQueryGeometry   PM:325; 

RM:284-286 

XtRAcceleratorTable  represen 
tation  type    PM:265 
XTranslateCoordinates  Xlib 

function    PM:373 
XtRBackingStore  representation 

type    PM:269 
XtRBitmap  representation  type 

PM:269 
XtRBool  representation  type 

PM:265 
XtRBoolean  representation  type 

PM:265 
XtRCallback  representation  type 

PM:270 
XtRCallProc  representation  type 

PM:25 1,268 
XtRCursor  representation  type 

PM:265, 269 
XtRDimension  representation 

type   PM:265 
XtR Display  representation  type 

PM:265 
XtRealizeWidget   PM:32, 35, 

156, 324, 332;  RM:287-288 
XtRealloc    PM:408;  RM:289 
XtRegisterCaseConverter 

PM:407;  RM:290     , 
XtRegisterGrabAction    PM:365; 

RM:29 1-292 

XtReleaseGC    PM:180;  RM:293 
XtRemoveAccelerators   PM:212 
Xt  Re  move  Action  Hook    PM:408; 

RM:294 

XtRemove Actions   PM:148 
XtRemoveAlLActions   PM:148 
XtRemoveAlICallbacks   RM:295 
XtRemoveCallback   PM:84, 372; 

RM:296 
XtRemoveCallbacks   PM:84; 

RM:297 
XtRemoveEventHandler 

PM:187, 226;  RM:298-299 
XtRemoveGrab   PM:385; 

RM:300 
XtRemovelnput   PM:232; 

RM:301 
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XtRemoveRawEventHandler 

PM:227;  RM:302-303 
XtRemoveTimeOut   PM:187, 

236;  RM:304 
XtRemoveWorkProc    PM:239; 

RM:305, 419 
XtResizeWidget   PM:324,331; 

RM:306 

XtResizeWindow   RM:307 
Xt  Resolve-Path  name    PM:409; 

RM:308-309 
XtResource    PM:248 
XtResourceDefaultProc 

RM:408 

example,  PM:268 
XtResourceQuark  address  mode 

constant   PM:273 
XtResourceString  address  mode 

constant   PM:273 
XtRFile  representation  type 

PM:265 
XtRFloat  representation  type 

PM:265 
XtR Font  representation  type 

PM:265 
XtRFontStruct  representation 

type    PM:265 
XtRFunction  representation  type 

PM:270 
XtRGeometry  representation 

type    PM:265 
XtRImmediate  representation 

type    PM:25 1,267 
XtRInitiuIState  representation 

type    PM:265 
XtRInt  representation  type 

PM:265 
XtRJustify  representation  type 

PM:269 
XtROrientation  representation 

type    PM:269 
XtRPixel  representation  type 

PM:265 
XtRPosition  representation  type 

PM:265 
XtRShort  representation  type 

PM:265 

XtRTranslationTable  represen 
tation  type    PM:265 
XtRUnsignedChar  representa 
tion  type    PM:265 
XtRVisual  representation  type 


PM:265 
XtRWidget  representation  type 

PM:269 

XtScreen    RM:310 
XtScreenOfObject   PM:404; 

RM:311 
XtSelectionCallbackProc 

PM:296,317;RM:409-410 
XtSelectionDonelncrProc 

PM:317;RM:411 
XtSelectionDoneProc    PM:296; 

RM:412 
XtSetArg    PM:55,  57,  100, 121; 

RM:312-313 
XtSetErrorHandler   PM:411; 

RM:314 
XtSetErrorMsgHandler 

PM:411;RM:315 
XtSetKeyboardFocus   PM:405; 

RM:316-317 

XtSetKeyTransIator   RM:318 
XtSetMappedWhenManaged 

RM:319 

XtSetMultiCikkTime    RM:320 
XtSetSelectionTimeout   PM:318, 

411;RM:321 
XtSetSensitive    PM:81,384; 

RM:322 
XtSetSubvalues   PM:280; 

RM:323-324,517 
XtSetTypeConverter 

PM:27 1-272;  RM:325 
arguments,  PM:270 
XtSetValues   PM:24, 51, 55, 156, 

159,331,349;RM:327-328, 

436 

XtSetValuesFunc    PM:180 
XtSetWarningHandier   PM:411; 

RM:329 
XtSetWarningMsgHandler 

PM:411;RM:331 
XtSetWMColormapWindows 

RM:332 
XtShellKxtcnsion  Version 

RM:455 
XtStringConversion  Warning 

RM:333 

XtSuperclass   RM:334 
XtTimeOut   PM:411 
XtTimerCallbackProc    RM:413 
XtToolkiflnitialize    RM:335 
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XtTranslateCoords   PM:80, 

372-373;  RM:336 
XtTranslateKey   PM:407; 

RM:337-338 
XtTransIateKeycode   PM:407; 

RM:339-340 

XtTypeConverter   RM:414-418 
XtUngrabButton    PM:409; 

RM:341 

XtUngrabKey   PM:409;  RM:342 
XtUngrabKeyboard    PM:409; 

RM:343 
XtUngrabPointer   PM:364, 409; 

RM:344 
XtUninstallTranslations 

RM:345 
XtUnmanageChild   PM:332; 

RM:346 
XtUnmanageChildren   PM:332; 

RM:347 
XtUnmapWidget  PM:332; 

RM:348 

XtUnrealizeWidget   RM:349 
XtVaAppCreateSheU   PM:413; 

RM:350 
XtVaAppInitiaUze    PM:32, 34; 

RM:351 

arguments,  PM:35 
fallback  resources  in,  PM:257 
shell  created,  PM:79 
XtVaCreateArgsLlst   RM:352 
XtVaCreateManagedWidget 

PM:32,35, 142,251;  RM:353 
XtVaCreatePopupShell   PM:79, 

360;  RM:354 
XtVaCreateWidget   PM:32,  67, 

142,251;RM:355 
XtVaGetApplicationResources 

RM:356 
XtVaGetSubresources   PM:279; 

RM:357 
XtVaGetSubvalues   PM:280; 

RM:358 
XtVaGetValues   PM:53, 138; 

RM:359 
XtVaSetSubvalues    PM:280; 

RM:360 
XtVaSetValues   PM:53, 138, 142, 

169-170, 178-181;  RM:361 
XtVersion  constant   PM:  1 53 
XtVersionDontCheck  constant 


PM:153 

XtWarning   PM:411;RM:362 
XtWarningMsg   PM:411; 

RM:363 
XtWidgetBaseOfTset  address 

mode  constant   PM:273 
XtWidgetGeometry   PM:332, 

335 
XtWidgetGeometry  structure 

PM:184-185 
XtWidgetToApplicationContext 

PM:236;  RM:364 
XtWindow   PM:  180, 391; 

RM:365 
XtWindowOfObject   PM:404; 

RM:366 
XtWindowToWidget   PM:404; 

RM:367 
XtWorkProc    PM:411; 

RM:419-420 
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